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Preface 



X/Cpen 



ent 



X/( )pen is an independi 
of t le world's largest 
con panics. Its mission is 
prai ;tical implementation i 



X/C)pe; 



3ns 



star dards 



strategy for 
into a c 
environment, called the 
cov ers the standards, 
systems. It provides for 
usei s to move between 



The components of the Cbmmon Applications Environment are defined in X/Open 
CA'.l Specifications. These contain, among other things, an evolving portfolio of 
practical application programming interfaces (APIs), which significantly enhance 
pori ability of application brograms at the source code level, and definitions of and 
references to, protocols and protocol profiles, which significantly enhance the 



inte 



roperability of applications 



The 



the 
the! • 
to 



, worldwide, open systems organisation supported by most 
infolrmation systems suppliers, user organisations and software 
:o bring to users greater value from computing, through the 
f open systems. 



achieving this goal is to combine existing and emerging 
omprehensive, integrated, high-value and usable system 
Common Applications Environment (CAE). This environment 
above the hardware level, that are needed to support open 
portability and interoperability of applications, and allows 
systems with a minimum of retraining. 



The X/Open CAE Specifications 
test; 1 and a distinct X/Opesn 
and may be carried only 
Spe ;ifi cations 



associated 



XPG brand, when 
unahibiguously to a procurer 
;orresponding X/Op^ 
procurements are therefore 
CAE Specifications 



tlie< 



X/Open is primarily conderned 
policy is to use formal approved 
wid sly supported de facto 



with the selection and adoption of standards. The 
de jure standards, where they exist, and to adopt 

sitandards in other cases. 



Where formal standards 
standards development on 
covering the needed funoions 
orgc nisations. Additionally 
fornjial approved standards 



are supported by an extensive set of conformance 
trademark - the XPG brand - that is licensed by X/ Open 
on products that comply with the X/Open CAE 



with a vendor's product, communicates clearly and 
that the software bearing the brand correctly implements 
CAE Specifications. Users specifying XPG-conformance in 
certain that the branded products they buy conform 



do not exist, it is X/Open policy to work closely with 
ganisations to assist in the creation of formal standards 
and to make its own work freely available to such 
X/Open has a commitment to align its definitions with 
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Preface 



X/C pen Specifications 
The re are two types of X/ (ppen specification: 
CAE Specifications 
AE (Common Applications 



fonn 



specifications that 
rhey are intended to 
ind procurement purploses 



be 



Developers who base t 



Environment) Specifications are the long-life 
the basis for conformant and branded X/ Open systems, 
used widely within the industry for product development 



leir products on a current CAE Specification can be sure that 



;ither the current specification or an upwards-compatible version of it will be 
^ferenced by a future XPG brand (if not referenced edready) , and that a variety of 
ompatible, XPG-branded systems capable of hosting their products will be 
ivailable, either immec lately or in the near future. 



AE Specifications an 
XPG brand, but are published 

;o its specifications in 
I ;onform to the CAE (and 
; is soon as practicable, 

o users. 



not published to coincide with the launch of a particular 
as soon as they are developed. By providing access 
this way, X/Open makes it possible for products that 
hence are eligible for a future XPG brand) to be developed 
enhancing the value of the XPG brand as a procurement aid 



^liminary SpeciGcations 



hese are specificatior|s 
I ;onsequently not yet s 
ihat are released in a 
jractical implementat 
draft" specification 
)ublication has gone 
)rocedures as a CAE 



usually addressing an emerging area of technology, and 
ijipported by a base of conformant product implementations, 
controlled manner for the purpose of validation through 
ion or prototyping. A Preliminary Specification is not a 
Indeed, it is as stable as X/Open can make it, and on 
rough the same rigorous X/ Open development and review 
Si)ecification. 



4' 



the 



reliminary Specificatii 

brmal standards org; 
develop products on 
technology that a Prelibiinary 

< nd may therefore char ge 

< ase the CAE Specification 
the corresponding Preliminary 

n all cases is not guaranteed 



In a idition, X/Open periodically publishes 



ihapshots 

Jnapshots are "draft" 
cjisseminate informaticin 

udience, in advance o 

omment. 



VI 



ons are analogous with the "trial-use" standards issued by 
lanisations, and product development teams are intended to 
basis of them. However, because of the nature of the 
Specification is addressing, it is untried in practice 
before being published as a CAE Specification. In such a 
will be made as upwards-compatible as possible with 
Specification, but complete upwards-compatibility 



documents, which provide a mechanism for X/Open to 

on its current direction and thinking to an interested 
formal publication, with a view to soliciting feedback and 
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Preface 



\ Snapshot represenis 
\lthough at the time 
owards publication of 
:onsensus organisatior , 



does 



Jimilarly, a Snapshot 
:o make any specific pijoducts 



X/C pen Guides 

X/()pen Guides provide 
pro :urement, developmer^t 
X/ ( )pen-compliant. 



X/Open Guides are not 



spe ;ifying or claiming X/Open-conformance 



Thi 5 Document 

The January 1987 edition 
stai dardise facilities by 
trar saction processing 
bidirectional interface betWeen 



interface). 



Thii 

Pre 
in 



The 



document is a CAE 



the interim results of an X/Open technical activity, 
of publication X/Open intends to progress the activity 
an X/ Open Preliminary or CAE Specification, X/Open is a 
, and makes no commitment regarding publication. 



not represent any commitment by any X/ Open member 
available. 



information that X/Open believes is useful in the evaluation, 
or management of open systems, particularly those that are 



normative, and should not be referenced for purposes of 



of the X/Open Portability Guide committed X/Open to 
rt^hich commercial applications could achieve distributed 
(pTP) on UNIX systems. This document specifies the 
a transaction manager and resource manager (the XA 



specification (see above), which was initially issued as a 
iminary Specification in April 1990, and reissued as a Snapshot of current thinking 
June 1991. This CAE rtiflects changes to the specification resulting from prototype 
imp lementations and committee and industry review. 

Thi$ specification is structured as follows: 

Chapter 1 is an introduction. 

hapter 2 provides fundamental definitions for the remainder of the document. 
( "hapter 3 is an overview of the XA interface, 
hapter 4 discusses the: data structures that are part of the XA interface, 
hapter 5 contains reference manual pages for each routine in the XA interface. 
(;^hapter 6 contains stat(5 tables. 

Chapter 7 summarises the implementation requirements and Identifies optional 
features. 



J *ippendix A is the code of the header file required by XA routines, 
e is an index at the end. 
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Preface 



Tyf ographical Conventio is 



The 



following typographical conventions are used throughout this document: 

ngs are code examples or literals and are to be typed just as 



onstant width str: 
hey appear. 



talk strings are used 
: equiring definition. It^ics 



- variable names 

- commands or utilities 

- functions; these are 
he notation "file.h" indicates 
he notation [ABCD] is 

tUipses (. . .) are used tc^ 



shown as follows: nameQ. 

a header, 
the name of a return value, 
show that additional arguments are optional. 



for emphasis or to identify the first instance of a word 
also denote: 
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Introduction 



The 



con ponents: 



\n application progreun (AP) defines transaction boundaries and specifies actions 
liat constitute a transaction. 

Resource managers (Rljvls, such as databases or file access systems) provide access 
0 shared resources. 



\ separate component 
ransactions, monitors 
;ompletion and for failiire 



Chi 



Thi:; 



Appl 



the XA interface: the bidirectional interface between a 
a resource manager. The XA interface is not an ordinary 



document specifies 
trarjsaction manager and 

ication Programmind Interface (API) . It is a system-level interface between DTP 
ware components. X/Open is developing other DTP interfaces for direct use by an 
appjlication program (see 5 ection 2.1 on page 3 for an overview). These interfaces may 
subject of future pubhcations. 



soft 
ap 
be 



tie; 



Chcjpfc 
the 
inte 
Chajpti 
this 
are 
and 



Chapter 1 



X/Open Distributed Transaction Processing (DTP) model envisages three software 



called a transaction manager (TM) assigns identifiers to 
their progress, and takes responsibility for transaction 
recovery. 



pter 2 defines each component in more detail and illustrates the flow of control. 



Thi;; specification is limited 
specification does not discuss 
X/C)pen anticipates that 
con munication of DTP 
inv( (Ive interfaces in additilon 
a mpre detailed DTP model. 



to the model presented in Section 2.1 on page 3. This 
aspects of the model that pertain to communication, 
heterogeneous TMs will use the OSI DTP protocols for 
irjformation and application data. Such communication will 
to the one described in this specification, and will involve 
. This is deferred to a later publication. 



iAF 



Cha])t( 



Relevant definitions and 
chapter also defines the 
;er 3 is an overview 
services is used 
interface. Reference manukl 
er 5; state tables foUpw 
specification on the 
optional. Appendix A 
Common Usage C. 



(|)ther important concepts are discussed in Chapter 2. This 
, TM and RM in more detail, and describes their interaction. 
c|f the XA interface, describing the situations in which each of 
er 4 discusses the data structures that are part of the XA 
pages for each routine in the XA interface are presented in 
in Chapter 6. Chapter 7 summarises the implications of 
implementors of RMs and TMs; it also identifies features that 
presents the contents of an "xa.h" header file in both ANSI C 
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Chapter 2 

Model and Definitions 



tfie 



Thi i chapter discusses 
background material for 
relationship of the interface 
des gn assumptions that 
con mon DTP concepts. 



X/Open DTP Model 

The figure below illustrates 
structure transactions. The 
mo( lei (see the definitions 
hich control flows. 



m v\ 



There 



may be several DTP 
figu re below are not nece: 
con rol (see Section 2.2.8 
hav i invariable roles. For 
sup 3ort of a transaction. 



The 
inte 

For 



XA interface in general terms and provides necessary 
the rest of the specification. The chapter shows the 
to the X/Open DTP model. The chapter also states the 
the interface uses and shows how the interface addresses 



on 



a local instance of a DTP system where an AP calls a TM to 
boxes indicate software components in the X/Open DTP 
in Section 2.2 on page 4). The arrows Indicate the directions 



systems coexisting on the same processor. The boxes in the 
^sarily separate processes, nor necessarily a single thread of 
page 6). Furthermore, the components of this model do not 
example, an RM might use the TX interface to do work in 



(] ) AP uses 
resi )urces from 
a set of EMs 



Resotrce 
Managers 
(RMCs) 



Application Program (AP) 



(3) TM and RMs exchange transaction information 



Int( rfaces between Local TP Components 



subject of this X/Opeii 
interface by which TMs and 



more details on this 
component, see the 



Transaction 
Manager 
(TM} 



(2) AP defines 
transaction 
boundaries 
tiirough the 
TX interface 



specification is interface (3) in the diagram above, the XA 
RMs interact. 



model and diagram, including detailed definitions of each 
referenped DTP guide. 
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Definitions 



Model and Definitions 



2.2 Di finitions 



2.2.2 



For 



additional definitions see the referenced DTP guide. 



2.2,1 Tr* nsaction 



A transaction is a completji 
wh ch may include user 
trai isaction modifies 
def nes transactions more 



Tra isactions must be able 
in r ssponse to a real-world 
roll back a transaction 
acci mnt may fail a test of 
sys em fails, keeping it 
soft ware component su 
trar saction that is rolled 



determines 



Wh^n the system 
it commits the 

effect. Either 
Coibpletion means either 



e unit of work. It may comprise many computational tasks, 
interface, data retrieval, and communications. A typical 
shardid resources. (The referenced OSI DTP specification (model) 
precisely.) 



to be rolled back. A human user may roll back the transaction 

event, such as a customer decision. A program can elect to 
or example, account number verification may fail or the 
its bcilance. Transactions also roll back if a component of the 
retrieving, communicating, or storing data. Every DTP 
to transaction control must be able to undo its work in a 
at any time. 



fram 
bjeict 
back 



that a transaction can complete without failure of any 
translaction. This means that changes to shared resources take 
commitment or rollback results in a consistent state, 
commitment or rollback. 



kinil 
per nanent 



Dis tributed Transaction Processing 

Wit lin the scope of this document, DTP systems are those where work in support of a 
sin§ le transaction may occ jr across RMs. This has several implications: 



'he system must have 



I lone anjrwhere in the s /stem. 



he decision to commi 



or roll back a transaction must consider the status of work 
I lone anywhere on behblf of the transaction. The decision must have uniform effect 
hroughout the DTP system. 



Evei though an RM may 
Qu(ry Language (SQL), it 
env ronment. 

2.2.3 Ap] )lication Program 

The AP defines transactions 
Bad 1 AP specifies a seque nee 
and databases. This specification 
inst mce of an application proi 



a way to refer to a transaction that encompasses all work 



have an X/Open-compliant interface, such as Structured 
must also address these two items to be useful in the DTP 



and accesses resources within transaction boundaries, 
of operations that involves resources such as terminals 
generally uses the term AP to refer to a single 

gram. 
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Definitions 



2.2 A Resource Manager 



An 



RM manages a certain 
sofil ware entities can 
thai the RM provides. 



k database managi 
defining transactions 



A. file access method 
the basis for an RM 
transactions as defined 



A. print server might b(! implemented as an RM. 



A 

se 
oth 



ser 'ices 



igle RM may service 

one of these domains 
rwise, operations thi^ 
insllance. 



on 
par 

Ag 
mu 
APs 



part of the computer's shared resources. Many other 
reqtjest access to the resource from time to time, using services 
are some examples of RMs: 

em^nt system (DBMS) is an RM. Typical DBMSs are capable of 
committing work atomically. 

as the Indexed Sequential Access Method (ISAM) can be 
Typically, an ISAM RM must be enhanced to support 
herein. 



and ( 



such ; 



2.2.5 Global Transactions 

Eve ry RM in the DTP envtironment 
2.2. 1 on page 4. Many RMp 



In t le DTP environment, 
Thi > unit of work is a 
sevjral different databases, 
committed atomically. 
units of work that are part 



. global 



Each 



Coirimitment of an RM' 
operations can succeed 
ren otely. If any operatioji 
operations it did on behal 
of t le work that other RMs 
dire cts the completion, of 
rec( iverable units of work 



2.2.6 Transaction Branches 



A diobal transaction has 
par of the work in 
eng age in a separate but 
fage 8). Each of the 
of exactly one branch. 



RM 



obal transaction might 
tiple processes or is 



Aft(!r the TM begins th^ 
additional work to do on 
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multiple independent resource domains. An RM instance 
(See also Section 3.2 on page 13.) Unless specified 
specification allows on an RM are allowed on each RM 



must support transactions as described in Section 
already structure their work into recoverable units. 



rnany RMs may operate in support of the same unit of work. 
transaction. For example, an AP might request updates to 
Work occurring anywhere in the system must be 
RM must let the TM coordinate the RM's recoverable 
of a global transaction. 



internal work depends not only on whether its own 

but also on operations occurring at other RMs, perhaps 
fails anywhere, every participating RM must roll back all 
of the global transaction. A given RM is typically unaware 
are doing. A TM informs each RM of the existence, and 
global transactions. An RM is responsible for mapping its 
:o the global transaction. 



cne 



or more transaction branches (or branches). A branch is a 
suppjort of a global transaction for which the TM and the RM 
coordinated transaction commitment protocol (see Section 2.3 
s internal units of work in support of a global transaction is 



have more than one branch when, for example, the AP uses 
ihvolved in the same global transaction by multiple remote 



transaction commitment protocol, the RM receives no 
that transaction branch. The RM may receive additional work 



Definitions 



Model and Definitions 



on )ehalf of the same transaction 
rela ted in that they must bb 



Each transaction branch 
the RM identifies 
this information to ( 



nyi ;s 



use 



Transaction Manager 



TM5 



manage global transcictions, coordinate the decision to commit them or roll them 
back, and coordinate faihire recovery. The AP defines the start and end of a global 
trar saction by calling a TM. The TM assigns an identifier to the global transaction (see 
Sec ion 4.2 on page 19). The TM manages global transactions and informs each RM of 
the XID on behalf of whic h the RM is doing work. Although RMs can manage their 
own recoverable work units as they see fit, each RM must accept XIDs and associate 
thei n with those work units. In this way, an RM knows what recoverable work units to 
con iplete when the TM completes a global transaction. 



Th) ead of Control 

A t iread of control (or a 
con ;rol of a processor. A 
spa:e and single thread 
required system resourc^, 
res( urces, and the files 
thrf ad of control must be 



Cer 



Many 



the 



from different branches. The different branches are 
completed atomically. 



idlentifier (or XID — see Section 4.2 on page 19) that the TM 
both a global transaction and a specific branch. The RM may 
optimise its use of shared resources and locks. 



thread) is the entity, with all its context, that is currently in 
thread of control is an operating-system process: an address 
control that executes within that address space, and its 
The context may include the process' locks on shared 
process has open. For portability reasons, the notion of 
(jommon among tiie AP, TM and RM. 



of 



the 



The thread concept is central 
woik, while TMs call RM$ 
that a given work request 
it fr 3m the same thread of control. 
start of a global transactio i 
regains control, it uses th^ 
recc ives the calls from the 



to the TM's coordination of RMs. APs call RMs to request 
to delineate transaction branches. The way the RM knows 
pertains to a given branch is that the AP and the TM both call 
For example, an AP thread calls the TM to declare the 
. The TM records this fact and informs RMs. After the AP 
native interface of one or more RMs to do work. The RM 
AP and TM in the same thread of control. 



;ain XA routines, therefore 
mai lual pages in Chapter 



Tightly- and Loosely-coupled Threads 



application threads 

work done in these 
transaction, the relationship 
coupled or loosely-coupled: 



1 \ tightly-coupled relationship 
resources. In addition 
treated as a single entity 
j ;uarantee that resource 



, must be called from a particular thread. The reference 
indicate which routines require this. 



of control can participate in a single global transaction. All 
threads is atomically completed. Within a single global 
between any pair of participating threads is either tightly- 



is one where a pair of threads are designed to share 
with respect to an RM's isolation policies, the pair are 
Thus, for a pair of tightly-coupled threads, the RM must 
deadlock does not occur within the transaction branch. 
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loosely-coupled relationship 
^M's isolation policies 
ransactions even thoui 



Wit lin a single global tranMction 
than just a pair. Moreove: 
sarr e global transaction an 
reference manual pages 
rela tionships to an RM 



a set of tightly-coupled threads may consist of more 
many sets of tightly-coupled threads may exist within the 
d each set is loosely coupled with respect to the others. The 
in Chapter 5 indicate how a TM communicates these 
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DeGnitions 



provides no such guarantee. With respect to an 
the pair may be treated as if they were in separate global 
;h the work is atomically completed. 



Specification 



Transaction 



Completion and Recovery 



Model and Definitions 



2.3 Ttc nsaction Completion and Recovery 



TMj and RMs use two-ph; 
refqrenced OSI DTP specification 



In flhase 1, the TM asks a 

Thi:; asks whether the RIV! 
An i^M may have to query 



If 

rep: 

negative 



the 

In 
trar 
Stat 
All 
TM 



RM can commit its v\ 
les affirmatively. A nei 
reply and rolling 
transaction branch. 



2.3.1 Ro 



The 



hase 2, the TM issues 
saction branch, as the 
ly records the fact thai 
RMs commit or roll ba,ck 
The TM can then discard 



ling Back the Global Transaction 



global 



TM rolls back the g. 
reqi[iest, or if the AP 

response vetoes 
s involvement in the g 

TM effects Phase 2 by 
let any changes to shared 
2 requests to RMs 
rfecord stably the decision 
trar saction. 



neg itive 
RM 

The 

not 
Phalse 
to 



transaction if any RM responds negatively to the Phase 1 
directs the TM to roll back the global transaction. Therefore, any 
the global transaction. A negative response concludes an 
obal transaction. 



2.3.2 Pro tocol Optimisations 



'. iead-only 

An RM can respond to 
asked to update shaded 
concludes the RM's 
Ihe TM and this RM 
] )articipating RMs, an 



] iowever, if the RM returns 
1 ransaction is prepared 
the RM may release 
c ctivity for that global 



1. Serialisabilit ^ 
serial sequer 
concurrent 



is a property of a set of 
ce of the transactions exists 
e fficution of the transaction. 



ase commit with presumed rollback, as defined by the 
(model). 



1 RMs to prepare to commit (or prepare) transaction branches, 
can guarantee its ability to commit the transaction branch, 
other entities internal to that RM. 



ork, it records stably the information it needs to do so, then 
gative reply reports failure for any reason. After making a 
back its work, the RM can discard any knowledge it has of 



all RMs an actual request to commit or roll back the 
case may be. (Before issuing requests to commit, the TM 
it decided to commit, as well as a list of all Involved RMs.) 
changes to shared resources and then return status to the 
its knowledge of the global transaction. 



telling all RMs to roll back transaction branches. They must 
resources become permanent. The TM does not issue 
responded negatively in Phase 1. The TM does not need 
to roll back nor the participants in a rolled back global 



the TM's prepare request by asserting that the RM was not 
resources in this transaction branch. This response 
involvement in the transaction; the Phase 2 dialogue between 
not occur. The TM need not stably record, in its list of 
that asserts a read-only role in the global transaction. 



does 
EMI 



the read-only optimisation before all work on the global 
global serialisability^ cannot be guaranteed. This is because 
transaction context, such as read locks, before all application 
t ransaction is finished. 



qoncurrent transactions. For a serialisable set of transactions, at least one 
that produces identical results, with respect to shared resources, as does 
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Model and L eGnitions 



2.3.4 



Dne-phcise Commit 

\. TM can use one-pha^e commit if it knows that there is only one RM anjwhere in 
he DTP system that is making changes to shared resources. In this optimisation, 
he TM makes its Phase 2 commit request without having made a Phase 1 prepare 

decides the outcome of the transaction branch and forgets 
ibout the transaction bi-anch before returning to the TM, there is no need for the TM 
o record stably these global transactions and, in some failure cases, the TM may not 
enow the outcome. 



2.3.3 Hei iristic Branch Completion 

Some RMs may employ 



heuristic decision-making: an RM that has prepared to 
conlmit a transaction branbh may decide to commit or roll back its work independently 
of the TM. It could then unlock shared resources. This may leave them in an 
state. When the TM ultimately directs an RM to complete the branch, the 
may respond that it h as already done so. The RM reports whether it committed 
or completed it with mixed results (committed some work 



incc nsistent : 
RM 
the 
and 



branch, rolled it back, 
rolled back other work). 



An RM that reports heuris'tic completion to the TM must not discard its knowledge of 
the transaction branch. Tlie TM calls the RM once more to authorise it to forget the 
branch. This requirement means that the RM must notify the TM of all heuristic 
dec sions, even those thct match the decision the TM requested. The referenced 
OSI DTP specifications (model) and (service) define heuristics more precisely. 



recc 



Moie 
sen; es 



Transaction Completion and Recovery 



ures and Recovery 



Fail 

A iJseful DTP system mufet 
devtce or medium, a comnjiunication 



Fail ares that a node can co Tect 



Fail ares that do not disrujl)t 
rolling back appropriate § 
faihire responds negative 
: gnise the XID. 



internally may not affect a global transaction. 

the commitinent protocol let the DTP system respond by 

ilobal transactions. For example, an RM recovering from a 
y to a prepare request based on the fact that it does not 



significant failures 
; the failure when an 



Failiire and recovery prodessin, 
refe -enced OSI DTP specifications 
X/ C ipen DTP model makes 



Ms and RMs have access 
Ms coordinate and control 



be able to recover from a variety of failures. A storage 
path, a node, or a program could fail. 



may disrupt the commitment protocol. The TM typically 
expected reply does not arrive. 



g in an X/Open DTP system is compatible with the 
, which define the presumed-roUback protocol. The 
these assumptions: 



to stable storage 
recovery 



RMs provide for their own restart and recovery of their own state. On request, an 
1 IM must give a TM a list of XIDs that the RM has prepared for commitment or has 
1 leuristically completed 
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Model and Definitions 
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/ 



OiapterS 

Interface Overview 



Th s chapter gives an 
TN! and the RM in an 
paj ;es for each routine in 
pn totypes. 



overview 



Th^ 

0 

API 



X/Open DTP model 
; Section 2.1 on page 
calling the TM or the 



of the XA interface. This is the interface between the 
X/Open DTP system. Chapter 5 contains reference manual 
alphabetical order. These pages contain C-language function 



3 



AP 



RM 




TM 


' 

XA 



envisages interfaces between each of the AP, RM, and TM 
. Generally, each use of the XA interface is prompted by the 
RM. 
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Index to Ser ices in the XA InterfaGe 



Index to Services in the XA Interface 



STame 



ax 

ax 



The 



Thd 
TM 



A 
6). 



The 
name 
RM 



reg 

unreg 



close 

commit 

complete 

end 
forget 

open 
prepare 

recover 

rollback 
start 



KM 



Register an 
Unregisterar 



to 



!thi3 



Terminate the 
Tell the RM 
Test an 
completion. 
Dissociate 
Permit the 
heuristically 
Initialise an 
Ask the RM 
branch. 
Get a list 



heuristically completed 



Tell the RM 
Start or 
XID with 
theRM. 



to 
resume 
future 



Interface Overview 



Description 



with a TM. 
RM with a TM. 



AP's use of an RM. 
commit a transaction branch. 
Asynchronous xa_ operation 



for 



thread from a transaction branch. 
RM to discard its knowledge of a 
completed transaction branch. 
BM for use by an AP. 
to prepare to commit a transaction 



of XIDs the RM has prepared or 



roll back a transaction branch, 
a transaction branch - associate an 
work that the thread requests of 



See 



Section 3.3.1 on page 16 
Section 3.3.1 on page 16 



3.2 


on 


page 


13 


3.4 


on 


page 


17 


3.5 


on 


page 


18 


3.3 


on 


page 


14 


3.4 


on 


page 


17 


3.2 


on 


page 


13 


3.4 


on 


page 


17 


3.6 


on 


page 


18 


3.4 


on 


page 


17 


3.3 


on 


page 


14 



RM 



ax_ routines let an 
rouj:ines let an RM dynam: 

xa_ routines are 
When an AP calls 
intelrface to inform RMs o: 
inte rface to do work in 
con imit or roll back 
rec( ivery. 

. tM must call the xa_ rotitines 
imare 



call a TM. All TMs must provide these routines. These 
cally control its participation in a transaction branch. 

supplied by RMs operating in the DTP environment and called by 
TM to start a global transaction, the TM may use the xa_ 
[the transaction branch. After the AP uses the RM's native 
of the global transaction, the TM calls xa_ routines to 
One other xa_ routine helps the TM coordinate failure 



support 
branches 



must call the xa_ 
When a TM invokes : 
arb: trary sequence. 



Not e: The routine name s in the xa_ series are only templates. 



actual names of these 
of a structure (see 



functions are internal to the RM. The RM publishes the 
Section 4.3 on page 21) that specifies the entry points to the 



in a particular sequence (see the state tables in Chapter 
than one RM with the same xa_ routine, it can do so in an 
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Opening and Closing Resource Managers 



Op 

In 



ening and Closing Resource Managers 



eich 1 



thread of control, 
that! thread before calling 
to d Issociate the AP from 



The 
RM 



the TM must call xa_openO for each RM directiy accessible by 
any other xa_ routine. The TM must eventually call xa_closeQ 
tieRM. 



If ai RM needs to take start-up actions (such as opening files, opening paths to a 
server, or resynchronising a node on the network), then it could do so when called by 
xa_i pen{). X/Open does r ot specify the actual meaning of xa_openQ and xa_doseO to 
an ?M, but the effect must be internal to the RM and must not affect transaction 
proi ;essing in either the calling TM or in other RMs. 

1 RM requires or accepts parameters to govern its operation (for example, a 
directive to open files for reading only), or to identify a target resource domain, then a 
string argument to xa_openQ conveys this information. If the RM does not require 
initialisation parameters, 1he string is typically an empty string. The xa_doseO call 
vise takes a string. 

TM; typically read the initialisation string from a configuration file. The xa_open{) 
roul ine, and the string form of its argument, support portability. A TM can give the 
inistrator control over every run-time option that any RM provides through 
xa_cjpen() with no reprogiamming or relinking. The administrator must only edit a 
con. iguration file or perform a comparable, system-specific procedure. 

TM calls xa_openQ with an identifier that the TM uses subsequently to identify the 
instance. A single RM may service multiple resource domains using multiple RM 
instances, if each instance supports independent treinsaction completion. For example, 
a sir igle database system rr ight access several data domains, or a single printer spooler 
mig It service multiple printers. The TM calls such an RM's xa_openi) routine several 
times, once for each instance, using string parameters that identify the respective 
reso Lirce. It must generate a different RM identifier for each call. 

To (inhance portability, RMs in the DTP environment should rely on the use of 
xg_c penQ in place of any r|on-standard open service the RM may provide in its native 
intei face. If an RM lets DTP applications call the native open routine, the effect must 
not ( onflict with the TM's v se of xa_open () . 
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Association }f Threads with Transaction Branches 



Association of Threads with Transaction Branches 



Several threads may 
Th( xa_start{) and xa_ent 
calling thread with a 
ass( )ciation with the branch 



A tl iread's association wit 



k thread is actively 
md has not made a 
ictive association with 



Certain calls to xa_end{) 
all may indicate that 
'esume the association 
yy/I may indicate that it 



suspend the thread's association (see Suspend below). The 
the association can migrate, that is, that any thread may 
In this case, the calling thread is no longer associated. (An 
does not support association migration.) 

thread calls xa_end{) to suspend its association but the association cannot migrate 
mother thread, the calling thread retains a suspended association with the 



If a 

to 

transaction branch. 



Sev 



start 

he primary use of xa_ 
his marks the start o 
:ontrol, uses the RM's 
: nade by the same thread 
rom the branch (see below) 



he return code from 
( ;ommitment of the transaction 
, global transactions may 
i ittentlon. 



Interface Overview 



participate in a single transaction branch, some more than once, 
routines pass an XID to an RM to associate or dissociate the 
brakich. The association is not necessarily the thread's initial 
; its dissociation is not necessarily the final one. 



1 a transaction branch can be active or suspended: 

associated with a transaction branch if it has called xa_startQ 
corresponding call to xa_endO. A thread is allowed only one 



each RM at a time. 



ral uses of xa_startO and xa_end() are considered below: 



start 0 is to register a new transaction branch with the RM. 
' the branch. Subsequently, the AP, using the same thread of 
native interface to do useful work. All requests for service 
are part of the same branch until the thread dissociates 



oin 

Another use of xa_start{) 
( :ertain form of xa_startQ 
QD. 



?Ms in the DTP environment 
them concurrently. If 
'. IM is free to serialise 
may block a second or 



iesume 

i \. special form of xa_si 
1 hat has been suspendeji 

nd 



xa_startO may indicate that the RM has already vetoed 
branch. This return code is not an error; rolled back 
be routine, while actual errors deserve the administrator's 



is to join an existing transaction branch. TMs must use a 
so that RMs can validate that they recognise the passed 



should anticipate that many threads will try to use 

jnultiple threads use an RM on behalf of the same XID, the 
threads' work in any way it sees fit. For example, an RM 
subsequent thread while one is active. 



tifirtO associates a thread with an existing transaction breinch 
(see below). 



A typical call to xa_end{) 
ind lets the branch he 
1 hread may use xa^starl Q 



dissociates the calling thread from the transaction branch 
completed (see Section 3.4 on page 17). Alternatively, a 
to rejoin the branch. 
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Transaction Context 



see 



RMs 



sns 



Suspend 

A form of xa_end{) 
transaction branch, 
incomplete state. By 
resumes its associatibn 
completely end the suspended 



Association of Threads with Transaction Branches 



pends, instead of ending, a thread's association with the 
This indicates that the thread has left the branch in an 
using the resume form of xa_start:0, it or another thread 
with the branch. Instead of resuming, the TM may 
association by using xa_encf(). 



Rollback-only 

An RM need not wait 
can return rollback 
use this knowledge 
transaction. An RM 
any time before it 
indicates that it does 



for global transaction completion to report an error. The RM 
as the result of any xa_start{) or xa_endQ call. The TM can 
;o avoid starting additional work on behalf of the global 
also unilaterally roll back and forget a transaction branch 
prepares it. A TM detects this when an RM subsequently 
riot recognise the XID. 



only ; 



Transaction branch stjates 

Several state tables 
affect the status of the 
on page 59 and Table 
4 on page 62). ATM 
calls in a sequence 



appear in Chapter 6. Each call to xa_startQ or xa_endQ may 
thread's association with a transaction branch (see Table 6-2 
iD-3 on page 60) and the status of the branch itself (see Table 6- 
must use these routines so that each thread of control makes 
complies with both tables. 



ithat 



R^4 



Tninsaction context is 
pri serve certain transaction 

join or resume cases 
av iilable enough transaction 
resource deadlock within 
m« ke available at least that 
suspend, as if the thread 
th] eads in the global transaction 



3.3.1 Re gistration of Resource Managers 



N< rmally, a TM involves 

RM switches, described 
associated with it.) Thp 
xaiprepareO, although an 
Section 2.3.2 on 
is discussed below, 



page 
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specific information visible to the AR The RM should 
context on xa_end () so that the RM can restore context in 
(defined above). In the join case, the RM should make 
context so that tightly-coupled threads are not susceptible 
the transaction branch. In the resume case, the RM should 
RM-specific transaction context present at the time of the 
had effectively never been suspended, except that other 
may have affected this context. 



all associated RMs in a transaction breinch. (The TM's set of 

in Section 4.3 on page 21 tells the TM which RMs are 

TM calls all these RMs with xa_startO, xa_end{), and 
RM that is not active in a branch need not participate further 
8). A technique to reduce overhead for infrequently-used 
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Threads with Transaction Branches 
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Dynamic Registration 

certain RMs, especially those involved in -l^tivelyfew f bal "O^^^^^ 
ttie TM to assume they ari not involved in a transaction. These RMs must register wiin 
the TM before they do ajplication work, to see whether the work is part ot a g™l 
trarisaction. The TM neUr calls these RMs with any form of xa.startQ. An RM 
de:lares dynamic registrition in its switch (see Section 4.3 on page 21). An RM can 
m ike this declaration only on its own behalf, and doing so does not change the TM's 
be haviour with respect t( ) other RMs. 

W hen an AP requests work from such an RM, before doing any work, the RM contacts 
th e TM by calling ax_rea(). The RM must call ax_reg{) from the same thread of control 
tl: at the AP would use if it called ax_reg() directly. The TM returns to the RM the 
a; )propriate XID if the A P is in a global transaction. 

li the thread ends its in/olvement in the transaction branch (using xa_encf()), then the 
E M must re-register (uj ing ax_reg{)) with the TM if the AP calls it for additional work 
ii 1 the global transaction If the RM does not resume its participation, then the TM does 



ot call the RM again fo 

the RM calls ax_reg{) 



that branch until the TM completes the branch. 



It the RM calls ax_regi) and the AP is not in a global transaction, the TM informs the 
I M, and remembers, tl at the RM is doing work outside any global transaction. In this 
(ase, when the AP completes its work with the RM, the RM must notify the TM by 
< alUng ax_unregQ. The RM must call ax_unregQ from the same thread of control from 
' vhich it called ax_regi). Until then — that is, as long as the AP thread involves the RM 
( )utside a global transaction — the TM neither lets the AP start a global transaction nor 
lets any RM register thjough the same thread to participate in one. 
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3.4 Bit nch Completion 



A 
RM 



calls xa_prepare{) to 
places any resources 
permanent if the TM su 
xa_roHback () , An 
subiequent xa_commitO or 
after responding to xa_pref are () 



A 
app 



TM 



to 



calls xa_commit{) 
ies permanently any 
resoturces it held on behalf 

a branch. The RM 
releases any resources it 



Befc re 



a TM can call xa 
letely ended with xi 
initiate branch completion 
1 thread from the 



coin pli 



sepj rate 

Opt imisations 

This section describes the; 
protocol. See Section 2.3.2 

Het ristic Decision 



The 
Sect 
the 



ask the RM to prepare to commit a transaction branch. The 
t holds in a state such that it can either make any changes 
bs ;quently calls xa_commit{) , or nullify any changes if the TM 
iiffirmative return from xa_prepareQ guarantees that a 
xa_roUback () succeeds, even if the RM experiences a failure 



direct the RM to commit a transaction branch. The RM 
;hanges it has made to shared resources, and releases any 
of the branch. A TM calls xa_rollback () to ask the RM to roll 
uhdoes any changes that it applied to shared resources, and 
hdd. 



prepare i) for a transaction branch, all associations must be 
_end{) (see Section 3.3 on page 14). Any thread can then 
That is, the TM may supervise branch completion with a 
threads that did work on behalf of the global transaction. 



AP 



use of xa_ routines in the standard two-phase commit 
m page 8 for other permissible sequences of these calls. 



X/Open DTP model 
on 2.3.3 on page 9) 
M permits this by calling 
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Branch Completion 



lets RMs complete transaction branches heuristiccilly (see 
RM cannot discard its knowledge of such a branch until 
xa_forgetQ for each branch. 



The 



Specification 
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f Chapter 4 

I The "xa.h"Hemer 



Thii 
pro 



poijits to an RM are contained in the RM's switch; see Section 4.3 on page 21.) This is 

an include file called "xa.h". Fully standardising this 



the 



infc rmatlon lets RMs be v bitten independently of the TMs that use them. It also lets 



use 



Ap] )endix A contains an "j :a.h" header file with #define statements suitable for ANSI C 
(see the referenced C stan lard) and Common Usage C implementations. This chapter 
con 



AN5IC 



4.1 Na ming Conventior s 



The XA interface uses 
reti rn codes. All names 
sect ion describes the XA 



he negative (error) 
: lon-negative return 



The 



TM; 



The 



chapter specifies stru 
ucts must adhere. It 



minimum content o 



s interchange TMs anc 



ture definitions, flags, and error codes to which conforming 
also declares the routines by which RMs call a TM. (Entry 



ains excerpts from the 



certain naming conventions to name its functions, flags and 
hat appear in "xa.h" are part of the XA name space. This 
naming conventions. 



he names of all TM 
heir negative (error) 
1 etum codes all begin 



codles returned by the xa_ routines all begin with XAER_. Their 

co< les all begin with XA_. 

fimctions that RMs call begin with ax_ (for example, ax_reg). 

return codes all begin with TMER_. Their non-negative 
\Hth TM_. 



•James of flags passed 
M. 



4.2 Tra nsaction Identific ation 



"xa.h" header defines 



without recompilatioi i, 



The XID structure is specified 
forn at identifier, two leng 
two contiguous componejits: 
qualifier {bqual). 



of 



gtrid_Iength element 
starting at the first byte 
elen ent specifies the numl&er 
byte after gtrid (that is 



RMs without recompiling. 



ANSI C code in "xa.h". The synopses in Chapter 5 also use 



to XA routines, and of flags in the RM switch, begin with 



a public structure called an XID to identify a transaction 
brarjch. RMs and TMs both use the XID structure. This lets an RM work with several 



in the C code below in struct xid_t. The XID contains a 
h fields and a data field. The data field comprises at most 
a global transaction identifier (gtrid) and a branch 



pecifies the number of bj^es (1-64) that constitute gtrid, 
" the data element (that is, at datalO]). The bqual_length 
of bytes (1-64) that constitute bqual, starting at the first 
data[gtrid_length]). Neither component in data is nuU- 
teranjinated. The TM need r ot initialise any unused bytes in data. 



It 
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Transaction 



IdentiBcation 



Alt lough "xa.h" constrain; ; 
XIE I, it does not specify th 
bqu 3I, taken together, mukt 
glo )al uniqueness is to i se 
ide: itlfiers (see the referem ;ed 
the XID's formatlD element 
fori latlD element should 1 )e 



XIE 
Thf 



con esponding branch. 



/* 
* 

*/ 
#de 
#de 



pas i a pointer to the XID, 



the 



bef( re returning. 



rransaction branch 

fine XIDDATASIZE 
fine MAXGTRIDSIZE 
#de:ine MAXBQUALSIZE 
str 



The "xa.h" Header 



the length and byte alignment of the data element within an 
data's contents. The only requirement is that both gtrid and 
be globally unique. The recommended way of achieving 
the naming rules specified for OSI CCR atomic action 
OSI CCR specification). If OSI CCR naming is used, then 
should be set to 0; if some other format is used, then the 
greater than 0. A value of -1 in formatID means that the 



is null. 

RM must be able \o map the XID to the recoverable work it did for the 



RMs may perform bitwise comparisons on the data 



con ponents of an XID for Lhe lengths specified in the XID structure. Most XA routines 



These pointers are valid only for the duration of the call. If 



needs to refer to th s XID after it returns from the call, it must make a local copy 



identification: XID and NULLXID: 



.2 8 

1 14 



ict xid_t { 
long formatID; 
1 ong gtrid_length ; 
1 ong bqual_length; 
char data [XIDDATASli: 



/* size in bytes */ 

/* maximum size in bytes of gtrid */ 
/* maximum size in bytes of bqual */ 



'* format identifier */ 

* value 1-54 */ 

* value 1-64 */ 
E] ; 



Struct xid t JID; 



typ^def 
/* 

* 1. value of -1 in fotrmatID means that the XID is null. 

*/ 

/* 

* ijeclarations of rou|tines by which RMs call TMs: 
*/ 

' XID *, long) ; 



ext( :rn int ax_reg ( int , 



ext< 



rn int ax_unreg ( in t , long) ; 
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4.3 Re source Manager S witch 



con 

swi 
cha 
the 



cai 



RMs 



TM administrator 
conltrolling the set of 
ch that gives the TM 
ige the set of RMs linked 
application. A different 
separate application executable 
share the RM's switch 



can 



An 



narjie 
tell 

the 

s 

22 



t(i 



uf ports 



RM's switch uses a 
, non-null pointers 
whether the RM uses 
RM operates asynchrjanously 

the migration 
defines constants usee 
dui ing the operation of th( ; 

/* 

CA Switch Data Structure 

*/ 

#de:ine RMNAMESZ 32 
#de:ine MAXINFOSIZE 256 
str 



}; 



add or remove an RM from the DTP system by simply 
linked to executable modules. Each RM must provide a 
access to the RM's xa_ routines. This lets the administrator 
with an executable module without having to recompile 
set of RMs and their switches may be linked into each 
module in the DTP system. Several instances of an RM 
structure. 



structure called xa_switch_t. The switch contains the RM's 
the RM's entry points, a flag and a version word. The flags 
dynamic registration (see Section 3.3.1 on page 15), whether 
(see Section 3.5 on page 18) and whether the RM 
of [associations (see Section 3.3 on page 14). Section 4.4 on page 
as these flags. The RM cannot change these declarations 
DTP system. 



jct xa_switch_t { 
< :har name [RMNAMESZ] ; 
ong flags; 
ong version; 
nt (*xa_open_entry) 
nt (*xa_close_entry) 
nt (*xa_start_entry) 
nt (*xa_end_entrY) { 
nt (*xa rollback 



nt (*xa_commit_en.try ) 
nt { *xa_recover_entr /) 



nt (*xa_f orget_entry 
nt (*xa_coinplete_en' 
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/* length of resource manager name, */ 

/* including the null terminator */ 

/* maximum size in bytes of xa_info strings, */ 

/* including the null terminator */ 



/* name of resource manager */ 
/* options specific to the resource manager */ 
/* must be 0 */ 
([shar *, int, long) ; /* xa_open function pointer */ 
{char *, int, long) ; /* xa_close function pointer */ 
(XID *, int, long) ; /* xa_start function pointer */ 
XtCD *, int, long) ; /* xa_end function pointer */ 
entcy) (XID *, int, long) ; 

/* xa_rollback fvmction pointer*/ 



nt (*xajprepare_entr ^r) (XID *, int, long) 



(XID *, 
(XID *, 



) (XID * 
(int 



try) 



int, long) 
long, int 

int, long) 
*, int * 



/* xa_prepare fTinction pointer */ 
/* xa_commit function pointer */ 

long) ; 

/* xa_recover fimction pointer */ 
/* xa_forget function pointer */ 
int, long) ; 

/* xa_complete function pointer*/ 
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init ons 



The 
oth 



Fl4g Definitions 

Thd XA interface uses 
wit iout change or reco: 
hea der, 



trie flag definitions. For a TM to work with different RMs 
nipilation, each RM uses these flags, defined in the "xa.h" 



"xa.h" header defines 
r flags are specified, 
in ilts switch (see Section 
TMp and RMs should use 
or ax_ call in which 



xa 



Fla I definitions for the XA interface are as follows: 



/* 
* 

*/ 

#de 



#de:ine TMREGISTER d 
#deEine TMNOMIGRATE 
#deEine TMUSEASYNC 



/* 
* 

*/ 
/* 



ise TMNOFLAGS, 
#de:ine TMASYNC 
#deEine TMONEPHASE 

#de:ine TMFAIL 



#de 
#de 
#de 



a constant, TMNOFLAGS, for use in situations where no 
An RM that does not use any flags to specify special features 
4.3 on page 21) should specify TMNOFLAGS. In addition, 
the same TMNOFLAGS constant as the flag argument in any 
do not use explicit options. 



thfy 



lag definitions for 

line TMNOFLAGS ( 



xOOOOOOOOL /* no resource manager features 
selected */ 

xOOOOOOOlL /* resource manager dynamically 
registers */ 

X00000002L /* resource manager does not support 
association migration */ 
(}x00000004L /* resource manager supports 
asynchronous operations */ 



lag definitions for 



definiid above, when not specifying other flags */ 



#de :ine 
#de ^ine 

#de line 

#de :ine 

#de :ine 



:ine 
ine 
:ine 



TMNOWAIT 
TMRESUME 

TMSUCCESS 

TMSUSPEND 

TMSTARTRSCMI 

TMENDRSCAN 
TMMULTIPLE 
TMJOIN 



#de:ine IMMIGRATE 
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the RM switch 



xa and ax routines 



CjxSOOOOOOOL /* perform routine asynchronously */ 
QX40000000L /* caller is using one-phase commit 

optimisation */ 
(|x20000000L /* dissociates caller and marks 

transaction branch rollback- only */ 
(jxlOOOOOOOL /* return if blocking condition exists */ 
(|x08000000L /* caller is resuming association 

with suspended transaction branch */ 
(Jx04000000L /* dissociate caller from transaction 
branch */ 

(|x02000000L /* caller is suspending, not ending, 

association */ 
dxOlOOOOOOL /* start a recovery scan */ 

(xOOSOOOOOL /* end a recovery scan */ 

(X00400000L /* wait for any asynchronous operation */ 
qxOOaooooOL /* caller is joining existing transaction 
branch */ 

(|x00100000L /* caller intends to perform migration */ 
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4.5 Return Codes 



As 



the ie 



with flag definitions, 
return codes, definedl 



/* 
*/ 



ix_() return codes ( 
tdeEine TM_JOIN 2 
#deEine TM RESUME 1 



#deEine TM_OK 
#deEine TMER_TMERR 

#deEine TMER_INVAL 
#deEine TMER PROTO 



* ca_() return codes ( resource manager reports to transaction manager) 

*/ 



#de 



ill TMs and RMs must ensure interchangeability by using 
" in the "xa.h" header. 



#deEine XA RBBASE 

ftdeEine XARBROLLBACK 

#deEine XA RBCOMMFAIL 

#deEine XA_RBDEADLOCK 
#deEine XA_RBINTEGRITY 

ideEine XA RBOTHER 



Eine XA RBPROTO 



#deEine XA_RBTIMEOUT 
#deEine XA_RBTRANSIENT 
#deEine XA RBEND 



tdeEine XA_NOMIGRATE 
Sdepine XA_HEURHAZ 
XA_HEURCOM 

#dejEine XA_HEURRB 
ftdeEine XA_HEURMIX 
#deEine XA RETRY 



#de Eine 
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ransaction manager reports to resource manager) 

/* caller is joining existing transaction 

branch */ 

/* caller is resuming association 
with suspended transaction branch */ 
/* normal execution */ 

/* an error occurred in the 

transaction manager */ 

/* invalid arguments were given */ 

/* routine invoked in an improper context */ 



LOO 

CA_RBBASE 

£A_RBBASE+1 

(A_RBBASE+2 
a_RBBASE+3 

CA_RBBASE+4 

CA_REBASE+5 

CA_RBBASE+6 
(A_RBBASE+7 
CA RBTRANSIENT 



/* the inclusive lower bound of the 

rollback codes */ 

/* the rollback was caused by an 

vmspecified reason */ 

/* the rollback was caused by a 

communication failure */ 

/* a deadlock was detected */ 

/* a condition that violates the 

integrity of the resources 

was detected */ 

/* the resource manager rolled back the 
transaction branch for a reason not on 
this list */ 

/* a protocol error occurred in the 
resource manager */ 

/* a transaction branch took too long*/ 
/* may retry the transaction branch */ 
/* the inclusive upper bound of the 
rollback codes */ 



/* resumption must occur where 

suspension occurred */ 

/* the transaction branch may have 

been heuristically completed */ 

/* the transaction branch has been 

heuristically committed */ 

/* the transaction branch has been 

heuristically rolled back */ 

/* the transaction branch has been 

heuristically committed and rolled back */ 

/* routine returned with no effect and 

may be reissued */ 
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#deEine XA_RDONLY 

tdepine XA_OK 

:ine XAER_ASYNC 
fine XAER RMERR 



#deE 
#deE 

#dgf 
#d€f 
#de fine 
#d€f 
#def 
#def 
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;ine 
line 



:ine 
line 
line 



XAER_NOTA 

XAER_INVAL 

XAER_PROTO 

XAER_EMFAIL 

XAER_DUPID 

XAER OUTSIDE 



The "xa.h" Header 



/* the transaction branch was read-only and 
has been committed */ 
/* normal execution */ 

2 /* asynchronous operation already outstanding */ 

3 /* a resource manager error occurred in the 
transaction branch */ 

4 /* the XID is not valid */ 

5 /* invalid arguments were given */ 

6 /* routine invoked in an improper context */ 

7 /* resource manager unavailable */ 

8 /* the XID already exists */ 

9 /* resource manager doing work outside */ 
/* global transaction */ 
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Reference Man ml Pages 



Thk chapter describes thle interfaces to the XA service set. Reference manual pages 
api tear in alphabetical on er, for each service in the XA interface. The ax_ routines are 
pre vided by a TM for use by RMs. The xa_ routines are provided by each RM for use 
byihe TM. 



Thi! symbolic constants 
Chipter 4). The state tj 
Ch ipter 6. 



Chapter 5 



and error names are described in the "xa.h" header (see 
bles referred to in the reference manual pages appear in 
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ax_reg() 

NAME 

ax_ 

SYNOPSIS 



#iiiClude "xa.h" 



inl 
ax 
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pel f( 



in 



cf 



reso iirce 



DESCRIPTION 

A 1 esource manager calls 
brm work on behalf 
1 urn, replies to the 
sh( uld be performed on 
del ermines that the callir 

im, xid points to a 
tra isaction, xfd points to 
wh ich xid points 



A esource manager 
wfich the application a( 
ad 'antage of this facility 
xa. switch_t structure 
[TIffiR_TMERR], when 



If 
inf 
[Tr)l. 
cal 
and 



If 

thi; 



Reference Manual Pages 



reg — dynamically reg ister a resource manager with a transaction manager 



regdnt rmid, XID 



ax_regO to inform a transaction manager that it is about to 
an application thread of control. The transaction manager, 
manager with an indication of whether or not that work 
behalf of a transaction branch. If the transaction manager 
g thread of control is involved in a branch, upon successful 
XID. If the resource manager's work is outside any global 
rkfULLXID. The caller is responsible for allocating the space to 



val.d 



mupt call this function from the same thread of control from 
cesses the resource manager. A resource manager taking 
r must have TMREGISTER set in the Hags element of its 
(see Chapter 4). Moreover, ax_reg() returns failure, 
isjsued by a resource manager that has not set TMREGISTER. 



WI :en the resource manaj 
is, when [TM_RESUME] 
gei lerate a unique branch 



If ihe transaction managfer 
gi\en to the resource manai 
[Tf IJOIN] . If the resouri :e 
it r lust return a failure indication 



he resource manager 
)rms the resource 
;_RESUME] is returnejd 
that suspended the 
does not recognise * 



t le 



transaction manage 
thread is loosely 
trahsaction. That is, the 
tra isaction with respect 
brc nch qualifier within 
sads in the same 
itly-coupled threads 
and that no 
tightly-coupled threads 



thr 
tig 

policies 
the se 



resot rce 



Tb ; implications of dynamically 
beg ins working on beh; 
xa_ start {) for all resour 



*xid, long flags) 



ger calls ax_reg{) for a new thread of control association (that 
is not returned; see below), the transaction manager may 
qualifier within the returned XID. 



elects to reuse within *xid a branch qualifier previously 
iger, it informs the resource manager of this by returning 
manager receives [TM_fOIN] and does not recognise *xid, 
to the application. 



is resuming work on a suspended transaction branch, it 
manager of this by returning [TM_RESUME]. When 
, xid points to the same XID that was passed to the xa_end{) 
ajssociation. If the resource manager receives [TM_RESUME] 
, it must return a failure indication to the application. 



x'ld 



: generated a new branch qualifier within the returned XID, 
coupled in relation to the other threads in this same global 
I esource manager may treat this thread's work as a separate 
;o its isolation policies. If the transaction manager reuses a 
returned XID, this thread is tightly-coupled to the other 
traitsaction branch. A resource manager must guarantee that 
are treated as a single entity with respect to its isolation 
deadlock can occur within the transaction branch among 



tl le 



registering are as follows: when a thread of control 
If of a transaction branch, the transaction manager calls 
:e managers known to the thread except those having 
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thi: 
cor 
res 
the ir 

Tb! 



<plicii ly 



tMREGISTER set in their 
flag set must exi 
trol is working on 
}urce managers knowh 
xa switch_t structur 5 



function's first arg 
wifen the transaction 
thread of control. 



the 
Th; 

T^ 



[TM. 



xa_switch_t structure. Thus, those resource managers with 
join a branch with ax_reg{). Secondly, when a thread of 
beialf of a branch, a transaction manager calls xa_end{) for all 
to the thread that either do not have TMREGISTER set in 
or have dynamically registered with ax_reg(). 



urgent, rmid, is the integer that the resource manager received 
manager called xa_openi). It identifies the resource manager in 



function's last argument, flags, is reserved for future use and must be set to 
NOFLAGS. 



from 



If the resource manai 
to the application. If 
a different thread 
manager expressed i 
flag on xa_endQ), the 
the work. Otherwisje 
manager must return 



that currently has 
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RETURN V|y.UE 

The function ax_regi) has |he following return values: 

[TlflJOIN] 

The resource managf ;r is joining the work of an existing transaction branch. The 
resource manager siould make available enough transaction context so that 
tightly-coupled threads are not susceptible to resource deadlock within the 
branch. If the resour ce manager does not recognise *xid, it must return a failure 
indication to the appi ication. 

[Trl4_RESUME] 

The resource manAger should resume work on a previously-suspended 
transaction branch. The resource manager should make available at least the 
transaction context tl lat is specific to the resource manager, present at the time of 
the suspend, as if the thread had effectively never been suspended, except that 
Other threads in the g obal transaction may have affected this context. 



;er does not recognise *xid, it must return a failure indication 
the resource manager allows an association to be resumed in 
the one that suspended the work, and the transaction 
;s intention to migrate the association (via the TMMIGRATE 
current thread may be different from the one that suspended 
the current thread must be the same, or the resource 
a failure indication to the application. 



reused branch qualifier, and the transaction manager has 
suspended thread associations for *xid, the following rules 



If *xid contains a 
multiple outstanding 

apply: 

• The transaction manager can have only one of them outstanding at any time 
with TMMIGRAT i set in Hags. 

Moreover, the tra isaction manager cannot resume this association in a thread 



a non-migratable suspended association. 



These rules prevent ambiguity as to which context is restored. 

OK] 

Normal execution. 
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[TJ|1ER_TMERR] 

The transaction majiager encountered an error in registering the resource 
manager. 

[TfjiERJNVAL] 

Invalid arguments w^re specified. 

[TrjlER_PROTO] 

The routine was invojied in an improper context. See Chapter 6 for details. 

SEE ALSO 

axhnregO, xa_endQ, xa_oAen(), xa_start(). 



WARNING 5 

If J 



id does not point to a 
ma / overwrite the caller's 
(orf a long word boundarj ) 
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buffer that is at least as large as the size of an XID, ax_regO 
data space. In addition, the buifer must be properly aligned 
in the event that structure assignments are performed. 
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NAME 



ax_ unreg — dynamically inregister a resource manager with a transaction manager 



SYNOPSIS 

#ii elude "xa.h" 



mt 



DESCRIPT 
A 



esource manager cal s ax_unreg{) to inform a transaction manager that it has 
coijipleted work, outsidt any global transaction, that it began after receiving the 

In addition, the resource manager is informing the 
he accessing thread of control is free to participate (from the 



Nl LLXID from ax_reg{ . 
tra isaction manager that 
res 



3urce manager's pers jective) in a global transaction. So long as any resource 
manager in a thread of control is registered with a transaction manager and is 
performing work outside any global transaction, that application thread cannot 
pai ticipate in a global trar saction. 

A tesource manager mu 
originally called ax_reg{). 
ha\ e TMREGISTER set in 
Moreover, ax_unregO 
ma lager that has not set 



Th( 



RETURN VALUE 

ax 



SEE ALSO 

ax 



unreg (int rmid, loig flags) 
ON 



ax_unreg() 



5t call this function from the same thread of control that 
A resource manager taking advantage of this facility must 
the flags element of its xa_switch_t structure (see Chapter 4). 
reljums failure [TMER_TMERR] when issued by a resource 
TMREGISTER. 



function's first argunrtient 
whfen the transaction 
the thread of control 



manai 



T^ NOFLAGS. 



, rmid, is the integer that the resource manager received 
ger called xa_openO. It identifies the resource manager in 



Thd function's last argurient. Gags, is reserved for future use and must be set to 



unregO has the foUowipg return values: 

[Tls|l_OK] 

Normal execution. 

[TIS|IER_TMERR] 

The transaction meirlager encountered an error in unregistering the resource 
manager. 

[TI\|IER_INVAL] 

Invalid arguments w^re specified. 

[T^|IER_PROTO] 

The routine was invoked in an improper context. See Chapter 6 for details. 



'-"egO- 
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xa_close [) 



NAME 



xa_ close — close a resoun e manager 



SYNOPSIS 

#i4 



mt 
xa 



DESCRIPT 
A 

the 
glo 

Thi 



IS a 



elude "xa.h" 



close (char *xa info 



ON 

t ransaction manager cs Us 
calling thread of conti ol. 
Dal transactions on behalf 



argument xa_info points 
insiance-specific informat on 
stri ig is 256 bj^es (includ ni 
an ;mpty string if the resc urce 
to tje available. The argunjient 



A 



acc ;sses 



transaction manager 
the resource 
ready closed have no 



rrjust call this function from the same thread of control that 
mar ager. In addition, attempts to close a resource manager that 
( ffect and return success, [XA_OK]. 



It i; an error, [XAER 
thn ad of control that is 
ma lager must call xa_en 
manager calls xa_closei) 
mai lager, an error, [XAER. 



Th€ 
call 

The 

TM 



tiat 



function's last argume nt, flags must be set to one of the following values: 
KSYNC 

This flag indicates 
success, the function 
use as an argument 
calling thread of con^ol 
same resource manag 



TM SfOFLAGS 



RETURN VALUE 
The 



argument rmid, the 
ng xa_open () , identifie; 



This flag must be usee 



[XAER_ASYNC] 

TMASYNC was set 
asynchronous operatibns 
Hags element of the resource 
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int rmid, long flags) 



xa_closei) to close a currently open resource manager in 
Once closed, the resource manager cannot participate in 
of the calling thread until it is re-opened. 

to a null-terminated character string that may contain 
for the resource manager. The maximum length of this 
g the null terminator). The argument xa_info may point to 
manager does not require instance-specific information 
xa_info must not be a null pointer. 



PRt)TO], for a transaction manager to call xa_closeQ within a 
s ssociated with a transaction branch (that is, the transaction 
i() before calling xa_cIoseQ). In addition, if a transaction 
' vhile an asynchronous operation is pending at a resource 
PROTO], is returned. 



same integer that the transaction manager generated when 
the resource manager called from the thread of control. 



to 



xa_closeO shall be performed asynchronously. Upon 
returns a positive value (called a handle) that the caller can 
xa_completeO to wait for the operation to complete. If the 
already has an asynchronous operation pending at the 
;r, this function fails, returning [XAER.ASYNCJ. 



when no other flags are set in flags. 



function xa_closeQ hasjthe following return values: 

[XA|_OK] 

Normal execution. 



in flags, and either the maximum number of outstanding 
has been exceeded, or TMUSEASYNC is not set in the 
manager's xa_switch_t structure. 
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[x4er_rmerr] 

An error occurred whjen closing the resource. 

[X4ER_INVAL] 

Invalid arguments w^re specified. 

[X4ER_PROTO] 

The routine was invoked in an improper context. See Chapter 6 for details. 

Thd function returns a pc sitive value upon success if the caller set TMASYNC (see 
abqve) in flags. 



SEE ALSO 

xa. 

WARNINGS 

Fro n 



the resource mana, 
duilation of the call to 
or 

wh^re xa_info points. 
info after the function 



er's perspective, the pointer xa_info is valid only for the 
xa_doseQ. That is, once the function completes, either 
;yn}:hronously or asynchronously, the transaction manager is allowed to invalidate 

Resource managers are encouraged to use private copies of 
;ompletes. 



s; 

V 

*xa 



xa_close () 



omplete Q , xajend () , xa. open () . 
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xa_comniit() 



NAME 

xa. 

SYNOPSIS 



commit — commit wo 



#ir elude "xa.h" 



int 
xa 



DESCRIPTllON 
A 



for 



c done on behalf of a transaction branch 



commit (XID *xid, iiit rmid, long flags) 



transaction manager cal 

ges made to resource; > 

manager may 
^xid must have been er 



cha 1 



trai saction : 



s xa_cominitQ to commit the work associated with *xid. Any 
held during the transaction branch are made permanent. A 
all this function from any thread of control. All associations 
ded by using xa_end() with TMSUCCESS set in flags. 



If a resource manager 
this function merely 
bra ich. A resource manag 
the iransaction manager a 

A ti ansaction manager 
thai accessed the resource 

The argument rmid, the 
calling xa_open () , identifie: 



Foil jwing are the valid settings of flags (note that at most one of TMNOWAIT and 
TmKsYNC maybe set): 



TMNOWAIT 

When this flag is 
[XA_RETRY] and doe|s 
effect). The function 
branch. TMNOWAIT 



TMASYNC 



This flag indicates 
success, the function 
use as an argument tc 
calling thread of cont 
same resource manqi) 
XAER_ASYNC]. 



already completed the work associated with *xid heuristically, 
reports how the resource manager completed the transaction 
er cannot forget about a heuristically completed branch until 
Is xa_forgetQ. 

mihst issue a separate xa_comniitO for each transaction bramch 
manager. 

^me integer that the transaction manager generated when 
the resource manager called from the thread of control. 



TMONEPHASE 

The transaction manager 
optimisation for the 

TMNOFLAGS 



Phis flag must be used 
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and a blocking condition exists, xa_commtO returns 
not commit the transaction branch (that is, the call has no 
Ka_commit{) must be called at a later time to commit the 
is ignored if TMONEPHASE is set. 



that 



xa_conimitQ shall be performed asynchronously. Upon 
i eturns a positive value (called a handle) that the caller can 
xa_completeO to wait for the operation to complete. If the 
■ol already has an asynchronous operation pending at the 
ger for the same XID, this function fails, returning 



sp ecified 



must set this flag if it is using the one-phase commit 
transaction branch. 



when no other flags are set in Hags. 
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RETURN VALUE 
Th( : 



[X/., 



[X/ 



[X/ 



[X/ 



_HEURMIX] 
Due to a heuristic de 
branch was partially 



[X4_RETRY] 

The resource managdr 
This value may be re turned 
was set. Note, howjever, 
TMNOWAIT is not 
unavailable). This va 
resources held on belhalf 
possible. The transacqion 



function xa_conunit{) las the following return values: 



he work done on behalf of the specified transaction branch 



HEURHAZ] 

Due to some failure 
may have been heuri^ically completed, 

HEURCOM] 

Due to a heuristic defcision, the work done on behalf of the specified transaction 
branch was committe : 



._HEURRB] 
Due to a heuristic de 
branch was rolled bac 



K. 



ision, the work done on behalf of the specified transaction 
dommltted and partially rolled back. 



S5t 



[XA.OK] 

Normal execution. 



[XA_RB*] 

The resource managei 
branch. Upon return 
has released all he 
TMONEPHASE is set 



[XA_RBROLLBACK] 



[XA_RBCOMMFAIL] 
A communication 
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xa_commit () 



ision, the work done on behalf of the specified transaction 



is not able to commit the transaction branch at this time, 
when a blocking condition exists and TMNOWAIT 
that this value may also be returned even when 
(for example, if the necessary stable storage is currently 
ue cannot be returned if TMONEPHASE is set in Hags. All 
of *xid remain in a prepared state until commitment is 
manager should reissue xa_conmit{) at a later time. 



did not commit the work done on behalf of the transaction 

the resource manager has rolled back the branch's work and 
d resources. These values may be returned only if 
in flags: 



The resource manager rolled back the transaction branch for an unspecified 

reason. 



failure occurred within the resource manager. 



[XA_RBDEADLOCK] 

The resource mar ager detected a deadlock. 

[XA_RBINTEGRITY] 

The resource mar^ger detected a violation of the integrity of its resources. 

[XA_RBOTHER] 

The resource mar 
this list. 



ager rolled back the transaction branch for a reason not on 
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xa_comn it () 



[XA_RBPROTO] 

A protocol error (j)ccurred within the resource manager. 

[XA_RBTIMEOUT] 

The work represehted by this transaction branch took too long. 

[XA_RBTRANSIENT] 

The resource marjager detected a transient error. 



[X/JER_ASYNC] 

TMASYNC was set 
asynchronous operati 
flags element of the 



[XAER_RMERR] 

An error occurred in 
branch and the brancft' 
signals a catastroph 
managers may success: 
should be returned o 
commit the branch 
state. Otherwise, [XA, 



SEE ALSO 
xa 



c mplete () , xa_forget () , x. Lopen () , xa_prepare () , xa_roUback () . 



WARNINGS 

Fror 1 
ofthle 

as 



Reference Manual Pages 



n flags, and either the maximum number of outstanding 
3ns has been exceeded, or TMUSEASYNC is not set in the 
resource manager's xa_switch_t structure. 



( ommitting the work performed on behalf of the transaction 
s work has been rolled back. Note that returning this error 
: event to a transaction manager since other resource 
fully commit their work on behalf of this branch. This error 
ily when a resource manager concludes that it can never 
that it cannot hold the branch's resources in a prepared 
RETRY] should be returned. 



ar id 



[XA|ER_RMFAIL] 

An error occurred tha^ makes the resource manager unavailable. 

[XA|£R_N0TA] 

The specified XID is n^t known by the resource manager. 

[XA^IRJNVAL] 

Invalid arguments wei p specified. 

[XAER_PROTO] 

The routine was invokled in an improper context. See Chapter 6 for details. 

The function returns a po itive value upon success if the caller set TMASYNC (see 
aboYe) in Hags. 



the resource managi 
call to xa_commitO 
onously, the transaction 
Resdurce managers are 
com )letes. 



yr chrc 



er :ou: 



■'s perspective, the pointer xid is valid only for the duration 
hat is, once the function completes, either synchronously or 
manager is allowed to invalidate where xid points, 
raged to use private copies of *xid after the function 
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ete 0 



SEE ALSO 

xa_ 
xa 



loseQ, ?ca_conmutQ , 
itartQ. 
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■a_end{), xa^forgetQ, xa_open[), xa_prepareQ, xa_roUbackQ, 
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NAME 

xa_jend — end work perfo 

SYNOPSIS 

ttirlclude "xa.h" 



xa 



end(XID *xid, int 



DESCRIPTIPN 
A 



t ransaction manager ce 
suspend work on, a 

of its work, eithei 
event in order to let 
;essfully returns, the 
branch but the brand i 
the same thread of cc 



poi tion 



son le 



sue 
the 
frodn 

At 



xa_ 
reg 



:mid, long flags) 



1 1 



ansaction manager 
ha\|e TMREGISTER set 
tarti), xa_endO is alsd 
stered with ax_regO 
loni ;er consider the callin] 
mu it consider the resoun 
the Dranch.) Thus, a resoui ce 
an : a_end() that suspends 
set n Gags) but before the 
mai lager. 



first argument, xid, is 



The 

san e XID that was either 



xa_end() 



med on behalf of a transaction branch 



lis xa_endQ when a thread of control finishes, or needs to 
transaction branch. This occurs when the application completes a 
partially or in its entirety (for example, before blocking on 
jther threads of control work on the branch). When xa_endQ 
c&lling thread of control is no longer actively associated with 
still exists. A transaction manager must call this function 
ntrol that accesses the resource manager. 



ah /ay 



s calls xa_end{) for those resource managers that do not 
the flags element of their xa_switch_t structure. Unlike 
issued to those resource managers that have previously 
After the transaction manager calls xa_endQ, it should no 
thread associated with that resource manager (although it 
e manager part of the transaction branch when it prepares 
manager that dynamically registers must re-register after 
its association (that is, after an xa_endQ with TMSUSPEND 
i pplication thread of control continues to access the resource 



thai 
reti rned. 



a pointer to an XID. The argument xid must point to the 
)assed to the xa_startO call or returned from the ax_regO call 
established the thread's association; otherwise, an error, [XAER_NOTA], is 



The argument rmid, the 
call ng xa_openQ, identifle; 



sjme 



Foil 3wing are the valid se 
TM SUCCESS orTMFAIL 



integer that the transaction manager generated when 
the resource manager called from the thread of control. 

tings of Eags (note that one and only one of TMSUSPEND, 
ijiust be set): 



TM SUSPEND 

Suspend a transactioi i 
resource manager tha ; 
working on a specific 
work on the branch 
TMMIGRATE flag, th 
association in the cui rent 
with either TMSUCCI SS 



TM: vlIGRATE 

The transaction manai 
a thread different fron i 
with TMSUSPEND 



branch on behalf of the calling thread of control. For a 
allows multiple threads of control, but only one at a time 
5ranch, it might choose to allow another thread of control to 
at this point. If this flag is not accompanied by the 
; transaction manager must resume or end the suspended 
thread. TMSUSPEND cannot be used in conjunction 
orTMFAIL. 



;er intends (but is not required) to resume the association in 
the calling one. This flag may be used only in conjunction 
and only if a resource manager does not have 
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xa_end { 



TMNOMIGRATE set 
IMMIGRATE in fla^ 
suspended with TM^ 
This is because a 
suspended thread 
flag is not used, a 
in the current thread. 
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in the flags element of its xa_switch_t structure. Setting 
s, while another thread's association for *xid is currently 
/[IGRATE, makes xa_endQ fail, returning [XAER_PROTO] . 
tra nsaction manager can have at any given time at most one 
ass 3ciation migrating for a particular transaction branch. If this 
transaction manager is required to resume or end the association 



TM SUCCESS 

The portion of work Jfas 
either TMSUSPEND c r TMFAIL 



TMFAIL 

The portion of work 
transaction branch as 
does so for the globa 
xa_endO returns one 
conjunction with eithe r 



TMi\SYNC 

This flag indicates 
success, the function 
use as an argument 
calling thread of conttol 
same resource mani; 
[XAER_ASYNC] 



RETURN V/ 

The 



LUE 

function xa_endQ has 



[XA NOMIGRATE] 

'he resource manager 



was unable to prepare the transaction context for migration. 

-lowever, the resourc i manager has suspended the association. The transaction 
t le association only in the current thread. This code may be 



manager can resume 

returned only when toth TMSUSPEND and IMMIGRATE are set in Bags. A 



resource manager that 



[XA. 



structure need not retqrn [XA_NOMIGRATE] 
OK] 

Nformal execution. 



succeeded. This flag cannot be used in conjunction with 
^/^p•A^ 



has failed. A resource manager might choose to mark a 
rollback-only at this point. In fact, a transaction manager 
transaction. If a resource manager chooses to do so also, 
of the [XA_RB*] values. TMFAIL cannot be used in 
TMSUSPEND orTMSUCCESS. 



tiat xa_endO shall be performed asynchronously. Upon 
eturns a positive value (called a handle) that the caller can 
xa_conipleteO to wait for the operation to complete. If the 
already has an asjmchronous operation pending at the 
iger for the same XID, this function fails, returning 



tc 



le following return values: 



sets TMNOMIGRATE in the flags element of its xa_switch_t 



[XAjRB*] 

'he resource manager 
ontrol and has marke 1 
bllowing values may I 



XA_RBCOMMFAIL] 
A communication 



has dissociated the transaction branch from the thread of 
rollback-only the work performed on behalf of *xid. The 
e returned regardless of the setting of flags: 



XA_RBROLLBACK] 

The resource maijager marked the transaction branch rollback-only for an 
unspecified reasor : 



ailure occurred within the resource manager. 
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xa_end () 



[XA_RBDEADLOCK 

The resource ma lager detected a deadlock. 

[XA_RBINTEGRITY] 

The resource mai lager detected a violation of the integrity of its resources. 

[XA_RBOTHER] 

The resource mana; 
reason not on thi: 



[XA_RBPROTO] 

A protocol error (Jccurred within the resource manager, 

[XA_RBTIMEOUT] 

The work represented by this transaction branch took too long. 

[XA_RBTRANSIENT] 

The resource mar ager detected a transient error. 



[X^ ER_ASYNC] 

TMASYNC was set 

asynchronous operat 
flags element of the re; 



flags, and either the maximum number of outstanding 
)ns has been exceeded, or TMUSEASYNC is not set in the 
ource manager's xa_switch_t structure. 



The 



unction returns a 
abo^e) in flags 

SEE ALSO 

3x_i^g{), xa^completeQ, xa_i 



WARNINGS 

Fror 1 the resource manage: 
of tl e call to xa^endQ. Th|it 
asyr chronously, the trans 
Rescurce managers are ericouraj 
com jletes 
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ger marked the transaction branch rollback-only for a 
ist. 



[XAER_RMERR] 

An error occurred in c^ssociating the transaction branch from the thread of control. 

[XA|ER_RMFAIL] 

An error occurred tha| makes the resource manager unavailable. 

[XAfeR_NOTA] 

The specified XID is n^t known by the resource manager. 

[XApRJNVAL] 

invalid arguments we\e specified. 

[XAfeR_PROTO] 

The routine was involtd 



in an improper context. See Chapter 6 for details, 
positive value upon success if the caller set TMASYNC (see 



( pen{),xa_start(). 



s perspective, the pointer xid is valid only for the duration 
is, once the function completes, either sjmchronously or 
ction manager is allowed to invalidate where xid points, 
ged to use private copies of *xid after the function 
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xa_forge:() 



NAME 

xa_ 

SYNOPSIS 



int 



forget — forget about 



#ii elude "xa.h" 



forget (XID *xid, i: it rmid, long flags) 



DESCRIPTllON 
A 



r jsource manager that 

bra ich must keep track 
cor imitted, rolled back, o: 
xa_ forget {) to permit the 
sue ;essful return, [XA_OI 
of view). A transaction 



Thf argument rmid, the i 
cal ing xa_open () , identifie; 

Th( function s last argum( 



Tlv ASYNC 



TMlNOFLAGS 

This flag must be use& when no other flags are set in flags. 

RETURN Vy^LUE 

The function xa_forgetQ hds the following return values: 



[X/ 
[X/ 

[X/ 

[X/ 
[X^ 



leuristically completes work done on behalf of a transaction 

if that branch along with the decision (that is, heuristically 
mixed) until told otherwise. The transaction manager calls 
resource manager to erase its knowledge of *xid. Upon 
] , *xid is no longer valid (from the resource manager's point 
manager may call this function from any thread of control. 



ame integer that the transaction manager generated when 
the resource manager called from the thread of control. 

nt, flags, must be set to one of the following values: 



tiat 



This flag indicates 
success, the function 
use as an argument t 
calling thread of con 

same resource mar ai 



[XAER_ASYNC]. 



xa_forget() shall be performed asynchronously. Upon 
returns a positive value (called a handle) that the caller can 
) xa_comp}ete{) to wait for the operation to complete. If the 
rol already has an asynchronous operation pending at the 
ger for the same XID, this function fails, returning 



_0K] 

Normal execution. 



ER_ASYNC] 
TMASYNC was set 
asynchronous operatjons 
Bags element of the 

ER_RMERR] 
An error occurred in 
forgotten the transaction 



.ER.RMFAIL] 
An error occurred tha : 

ER_NOTA] 
The specified XID 13 
completed XID. 
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heuristically completed transaction branch 



n flags, and either the maximum number of outstanding 
has been exceeded, or TMUSEASYNC is not set in the 
manager's xa_switch_t structure. 



re lource 



the resource manager and the resource manager has not 
branch. 



makes the resource manager unavailable. 



not known by the resource manager as a heuristically 
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[XiKERJNVAL] 

Invalid arguments w^re specified. 

[X^ER_PROTO] 

The routine was invoked in an improper context. See Chapter 6 for details. 

Th ; function returns a p )sitive value upon success if the caller set TMASYNC (see 
abcfve) in Bags. 



SEE ALSO 
xa 



commitQ , xa_complete{) 



WARNINGS 

Fr( 
of 



Frqm the resource manag 

call to xa_forgetQ. 
asjjnchronously, the tran: 
Resource managers are 
cor ipletes. 



xa_forget () 



r's perspective, the pointer xid is valid only for the duration 
lat is, once the function completes, either synchronously or 
action manager is allowed to invalidate where xid points. 
Encouraged to use private copies of *xid after the function 



xa_open{), xa_recoverO, xa_roUbackQ. 
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xa_open () 



NAME 



xa. open — open a resour e 



SYNOPSIS 

#iilclude "xa.h" 

int 

xa open ( char *xa_info 

DESCRIPTJON 

A t ransaction manager Cc 
for use in a distributed 
ma lagers that support th( 
ma lager (xa_) calls are m 



an 



s xa_openQ to initialise a resource manager and prepare it 

ransaction processing environment. It applies to resource 
notion of open and must be called before any other resource 
de. 



Th( argument xa_info po 
ins ance-specific informat 
stri ig is 256 bytes (incluc 
!mpty string if the 



nts to a null-terminated character string that may contain 
on for the resource manager. The maximum length of this 
ng the null terminator). The argument xajtnfo may point to 
resc urce manager does not require instance-specific information 
to tie available. The argun ent xa_info must not be a null pointer. 



The argument rmid, an int^i 
the called resource man; 
mai lager passes the rmid 
mai lager. This identifier 
clos es the resource managfer 



ger assigned by the transaction manager, uniquely identifies 
[er instance within the thread of control. The transaction 
m subsequent calls to XA routines to identify the resource 
r ;malns constant until the transaction manager in this thread 



The 

[XA. 



that 



If tl e resource manager silpports 
xa_i )pen () more than once 
gen irates a new rmid valu 
eacl I call, typically to ident fy th( 

A t: ansaction manager m 
accesses the resource mana; 
inst mce that is already 

The function's last argumejit 

TM, ssmc 

This flag indicates 
success, the function 
use as an argument 
calling thread of cont 
same resource manag< 

TMl JOFLAGS 

This flag must be used 

RETURN V^LUE 

! [unction xa_o|penO has 

OK] 

Normal execution 
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manager 



int rmid, long flags) 



multiple instances, the transaction manager can call 
for the same resource manager. The transaction manager 
for each call, and must use different values for *xa_info on 
e respective resource domain. 

ist call this function from the same thread of control that 
ger. In addition, attempts to open a resource manager 
have no effect and return success, [XA_OK]. 



. flags, must be set to one of the following values: 



tc 



xa_open{) shall be performed asynchronously. Upon 
eturns a positive value (called a handle) that the caller can 
xa_completeO to wait for the operation to complete. If the 
ol already has an asynchronous operation pending at the 
, this function fails, returning [XAER_ASYNC]. 

when no other flags are set in flags. 

he following return values: 
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[xj: 

[XP 

[X/ 

The 
abo /e) 

SEE ALSO 

xailose () , xa_complete () . 

WARNING* 

Froiri the resource manader's perspective, the pointer xa_info is valid only for the 
duntion of the call to pfa_openO- That is, once the function completes, either 
syni hronously or as3mchrbnously, the transaction manager is allowed to invalidate 
where xa_info points. Resource managers are encouraged to use private copies of 
*xa_ info after the function dompletes. 



R_ASYNC] 

MASYNC was set tn Hags, and either the maximum number of outstanding 
asynchronous operations has been exceeded, or TMUSEASYNC is not set in the 
flags element of the resource manager's xa_switch_t structure. 

R_RMERR] 

An error occurred wh^n opening the resource. 

ERJNVAL] 
nvalid arguments we|re specified. 

R_PROTO] 

he routine was invoAed in an improper context. See Chapter 6 for details. 

'unction returns a pqsitive value upon success if the caller set TMASYNC (see 
infla^. 



xa_open() 
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xa_prepcre () 



NAME 



xa_ prepare — prepare to i ommlt work done on behalf of a transaction branch 



SYNOPSIS 



int 

xa_ prepare (XID *xid, 



DESCRIPT 
At 

cori 



ON 



ansaction manager ca 
imitment any work 

it held or 
n it receives a 
ommitQ). If the trans 
ubjsequent calls to xa_ 
this function from an^ 
by using xa_end () w 



resi )urces 
wh 

xa 
s 

cai: 

ended 



Oni :e this function successjfuUy 
trai saction branch may b 
res( urce manager cannot 
either Aa_co/ninit() or 



in optimisation, a rest urce manager may indicate either that the work performed 
)ehalf of a transaction aranch was read-only or that the resource manager was not 



The 
cal 



The 



tm: 



lude "xa.h" 
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nt rmid, long flags) 



Is xa_prepare () to request a resource manager to prepare for 
pe rformed on behalf of *xid. The resource manager places any 
modi led in such a state that it can make the results permanent 
commit request (that is, when the transaction manager calls 
iction branch has already been prepared with xa_prepare{) , 
pnpareQ return [XAER_PROTO]. A transaction manager may 
thread of control. All associations for *xid must have been 
1th TMSUCCESS set in flags. 



returns, the resource manager must guarantee that the 
; either committed or rolled back regardless of failures. A 
( rase its knowledge of a branch until the transaction manager 
<a_rollbackQ to complete the branch. 



cal 

As 
on 

accf ssed on behalf of a branch (that is, xa^prepareQ may return [XA_RDONLY]). In 
eithsr case, the resource 
brai ich. 



meinager may release all resources and forget about the 



A ti ansaction manager 
that accessed the resource 



s ime 



argument rmid, the 
i ng xa_open (), identifies! the 



milst issue a separate xa_prepare () for each transaction branch 
nanager on behalf of the global transaction. 

integer that the transaction manager generated when 
resource manager called from the thread of control. 



It xa_prepareO shall be performed asynchronously. Upon 
eturns a positive value (called a handle) that the caller can 
xa_completeO to wait for the operation to complete. If the 
ol already has an asynchronous operation pending at the 
ger for the same XID, this function fails, returning 



sIOFLAGS 
This flag must be used 



function's last argume^it. Bags, must be set to one of the following values: 

TM, VSYNC 

This flag indicates th 
success, the function 
use as an argument tc 
calling thread of cont 
same resource man 
[XAER_ASYNC]. 



when no other flags are set in Hags. 
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RETURN VA 
Th< 



[X/ 



[X/ 



,UE 

iinction xa_prepare () 
RDONLY] 

he transaction branch 
OK] 

Mormcd execution. 



RB*] 

'he resource manage 
transaction branch 
aranch's work and h^ 
returned: 



[xa: 



[XAi;: 



[xa: 



las the following return values: 



was read-only and has been committed. 



did not prepare to commit the work done on behalf of the 

Jpon return, the resource manager has rolled back the 
released all held resources. The following values may be 



:XA_RBROLLBACK] 

The resource ma|iager rolled back the transaction branch for an unspecified 

reason. 



:XA_RBCOMMFAIL] 
A communicatioi 

XA_RBDEADLOCK 
The resource mana; 



R_ASYNC] 

MASYNC was set 
as3mchronous operati(|ns 
flags element of the 

R_RMERR] 
he resource manage 
ransaction branch's 



R_RMFAIL] 

\n error occurred tha 
CID may or may not h£|ve 
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xa_prepare() 



'ailure occurred within the resource manager. 



ger detected a deadlock. 

:XA_RBINTEGRITY] 

The resource mar^ager detected a violation of the integrity of its resources. 

XA_RBOTHER] 

The resource mai|ager rolled back the transaction branch for a reason not on 
this list. 



xurred within the resource manager. 



XA_RBPROTO] 
A protocol error i 

:XA_RBTIMEOUT] 

The work represe]|ited by this transaction brcinch took too long. 

XA_RBTRANSIENT 
The resource 



man iger 



• detected a transient error. 



res lurce 



flags, and either the maximum number of outstanding 
has been exceeded, or TMUSEASYNC is not set in the 
manager's xa_switch_t structure. 



;r encountered an error in preparing to commit the 
The specified XID may or may not have been prepared. 



w( irk 



makes the resource manager unavailable. The specified 
been prepared. 



pecification 
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xa_prep£re() 



ER_NOTA] 

The specified XID is r|ot known by the resource manager. 

[X4ER_INVAL] 

Invalid arguments wdre specified. 



[X/ 



The 



ER_PROTO] 

The routine was invo 



'unction returns a pc 
abc^e) in flags. 



SEE ALSO 

xa 



vmmitO , xa^completeQ 



WARNINGS 

Fn 
of 



?f r 



Froin the resource managi 
call to xa_prepare () . 
asyjichronously, the transaction 
)urce managers are eircoura] 
pletes. 



Res 
con 
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ed in an improper context. See Chapter 6 for details. 

sitive value upon success if the caller set TMASYNC (see 

xa_open () , xa_roUback () . 
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s perspective, the pointer xid is valid only for the duration 
hat is, once the function completes, either synchronously or 
manager is allowed to invalidate where xid points, 
iged to use private copies of *xid after the function 
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NAME 



xa 



recover — obtain a list 



SYNOPSIS 

#ir 

int 
xa 



xa_recover() 



of prepared transaction branches from a resource manager 



elude "xa.h" 



recover (XID *xids, 



DESCRIPTION 

A t ansaction manager ca 
bra iches that are curren 
poiits xids to an array 
trai isactions, and sets com t 



s xa_recoverO during recovery to obtain a list of transaction 
in a prepared or heuristically completed state. The caller 
into which the resource manager places XIDs for these 
to the maximum number of XIDs that fit into that array. 



So ihat all XIDs may be re 
xa_ ^ecoverO calls may be 
xa_ ecoverO defines when 
start of a recovery scan 
heu ristically completed 
the current position in 



urned irrespective of the size of the array xids, one or more 
used within a single recovery scan. The flags parameter to 
a recovery scan should start or end, or start and end. The 
moves a cursor to the start of a list of prepared and 
transactions. Throughout the recovery scan the cursor marks 
list. Each call advances the cursor past the set of XIDs it 



thit 



reti ms. 



Tw( I consecutive complet 
unli iss a transaction manai 
for ;hat resource manage: 
sorr e branches, between t 



A tr msaction manager ma 
agi' 



ren recovery scan musi 

Upc n success, Aa_recoverO 
The function returns the 
com t, there are no more 
tran saction manager need 

Mul :iple invocations of 
com aleted transaction brar 



It is ;he transaction manage 

The argument rmid, the s; 
calli ig xa_open (), identifies |the 

Folk iwing are the valid sett 

TMJTARTRSCAN 

This flag indicates tha 
:ontrol and position tHe 
3oint. If a recovery sc in 
;nded and then restarti id 



TMI NDRSCAN 

This flag indicates tha 
he XIDs. If this flag 
ia_recoverQ call starts 



long count, int rmid, long flags) 



recovery scans return the same list of transaction branches 
er calls xa^commitQ, xa_forget{), xa_prepareO, or xa__rollbackQ 
or unless that resource manager heuristically completes 

e two recovery scans. 

call this function from any thread of control, but all calls in 
be made by the same thread. 

places zero or more XIDs in the space pointed to by xids. 
njjmber of XIDs it has placed there. If this value is less than 
XIDs to recover and the current scan ends. (That is, the 
lot call xa_recover 0 again with TMENDRSCAN set in Sags.) 
Ka_recoverQ retrieve dl the prepared and heuristically 
ches. 



r's responsibility to ignore XIDs that do not belong to it. 



me integer that the transaction manager generated when 
resource manager called from the thread of control. 

ngs of flags: 

xa_recoveri) should start a recovery scan for the thread of 

cursor to the start of the list. XIDs are returned from that 
is already open, the effect is as if the recovery scan were 



xa_recoverO should end the recovery scan after returning 
s used in conjunction with TMSTARTRSCAN, the single 
5 nd then ends a scan. 
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xa_recov;r 0 



T1S4NOFLAGS 

This flag must be use 
already be started 
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when no other flags are set in Hags. A recovery scan must 
Xlps are returned starting at the current cursor position. 



RETURN Value 

function xa_recover() \ 



The 



as the following return values: 



As a return value, :^_recoverQ normally returns the total number of XIDs it 
returned in *xids. 

R_RMERRI 

An error occurred in determining the XIDs to return. 



[XAER_RMFAIL] 

An error occurred tha 



[XApRJNVAL] 

'he pointer xids is Nl 

flags was specified, oi 
and did not specify 



[XA 



SEE ALSO 

xaSmmitQ, xa_forgetQ,xa_ 

WARNINGS 

If xi Is points to a buffer 
over write the caller's data 



^L and count is greater than 0, count is negative, an invalid 
the thread of control does not have a recovery scan open 
TIf STARTRSCAN in flags. 



R_PROTO] 

'he routine was involdsd in an improper context. See Chapter 6 for deteiils. 



makes the resource manager unavailable. 



open 0 , xa_wUback 0 . 



tHat cannot hold all of the XIDs requested, xa_recoverO may 
s jace. 
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NAME 

xa. 

SYNOPSIS 



"oUback — roll back werk done on behalf of a transaction branch 



#inc 



mt 
xa 



rollback (XID *xid, lint rmid, long flags) 



DESCRIPTI N 

A 



ti ansaction manager calls xa_rollback () to roll back the work performed at a resource 
ger on behalf of the transaction branch. A branch must be capable of being rolled 
until it has successfully committed. Any resources held by the resource manager 
le branch are releasee] and those modified are restored to their values at the start 
branch. A transactiori manager may call this function from any thread of control. 



maipai 
bac 
for 
of tie 



xa_rollback () 



lude "xa.h" 



r !Source manager can Forget a rolled back transaction branch either after it has 
noticed all associated tnreads of control of the branch's failure (by returning 
[XA iR_NOTA] or [XA_Rb*] on a call to xa^endQ), or after the transaction manager 
calli it using xa_startQ wijh TMRESUME set in flags. The transaction manager must 
ensi re that no new threads of control are allowed to access a resource manager with a 
roUe d back (or marked rollback-only) XID. 

In i ddition, xajcollback () Imust guarantee that forward progress can be made in 
rele; sing resources and rastoring them to their initial values. That is, because this 
func tion may be used by [a transaction manager to resolve deadlocks (defined in a 
manner dependent on tife transaction manager), xa_rollbackQ must not itself be 
susc sptible to indefinite blacking. 

If a esource manager already completed the work associated with *xid heuristically, 
this function merely reports how the resource manager completed the transaction 
bran :h. A resource managar cannot forget about a heuristically completed branch until 
the t 'ansaction manager cals xa_forgetQ . 

A tn nsaction manager mult issue a separate xa_rollbackO for each transaction branch 
that accessed the resource nianager on behalf of the global transaction; 



The argument rwid, the sa 
callir gxa_openQ, identifies | 

The unction's last argumei 

TM/HSYNC 

'his flag indicates th 



le integer that the transaction manager generated when 
le resource manager called from the thread of control. 

L flags, must be set to one of the following values: 



xa_rollback{) shall be performed asynchronously. Upon 
! uccess, the function rlturns a positive value (called a handle) that the caller can 
1 ise as an argument to vca_completeO to wait for the operation to complete. If the 
( ailing thread of control already has an asynchronous operation pending at the 
ame resource manager for the same XID, this function fails, returning 
XAER_ASYNC]. 



TMIvOFLAGS 

'his flag must be used 



/hen no other flags are set in flags. 
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RETURN V I 
Thf 
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LUE 

function xa_roUback () 



[X4 HEURHAZ] 

Due to some failure 
may have been 
value only if it has 

[X^ HEURCOM] 

Due to a heuristic de 
aranch was committe 
successfully preparec 

[XALHEURRB] 

Due to a heuristic 
jranch was rolled ba( 
uccessfully preparec 

[xaLheurmix] 

Due to a heuristic 
branch was partially 
may return this value 

[xaIok] 

Normal execution. 



las the following return values: 



le work done on behalf of the specified transaction branch 
heuijistically completed. A resource manager may return this 
fully prepared *xid. 



su( cess: 



ision, the work done on behalf of the specified transaction 
A resource manager may return this value only if it has 
xid. 

decision, the work done on behalf of the specified transaction 
. A resource manager may return this value only if it has 
xid. 



decision, the work done on behalf of the specified transaction 
ommitted and partially rolled back. A resource manager 
)nly if it has successfully prepared *xid. 



[XA|.RB*] 

he resource manage 
released all held resources 
was already marked n 
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has rolled back the transaction branch's work and has 
These values are typically returned when the branch 
Iback-only. The following values may be returned: 



XA_RBROLLBACK] 

The resource mar[ager rolled back the transaction branch for an unspecified 
reason. 

:XA_RBCOMMFAIL] 

A communication [failure occurred within the resource manager. 

XA_RBDEADL0CK] 

The resource manager detected a deadlock. 

XA_RBINTEGRITY] 

The resource manager detected a violation of the integrity of its resources. 

XA_RB0THER] 
The resource 
this list. 



man iger 



rolled back the transaction branch for a reason not on 



XA_RBPR0T0] 

A protocol error ocjcurred within the resource manager. 

XA_RBTIME0UT] 

The work represerAed by this transaction branch took too long. 
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XA_RBTRANSIENT 

The resource mai lager detected a transient error. 

[x4er_async] 

TMASYNC was set 
asynchronous operations 
Bags element of the resource 



[XA 



ER_RMERR] 

An error occurred in ijolUn! 
xee to forget about t le 
threads of control hav i 



[X^ER_RMFAIL] 

An error occurred tha 

[XyiJER_NOTA] 

The specified XID is n 

[XApRJNVAL] 

nvalid arguments we 

[XA|ER_PROTO] 

The routine was invo' 



The function returns a po 
abo ^e) in flags 



SEE ALSO 

xa 



c omwitQ, xajcompletei) 



WARNINGS 



Frorp 
of 



n flags, and either the maximum number of outstanding 
has been exceeded, or TMUSEASYNC is not set in the 
manager's xa_switch_t structure. 



makes the resource manager unavailable. 



)t known by the resource manager. 



ed 



tt le 



the resource manage 
call to xa_ro}lbackQ 
or aiynchronously, the transaction 
Resc urce managers are 
com Dletes. 



xa_rollback() 



g back the transaction branch. The resource manager is 
branch when returning this error so long as all accessing 
been notified of the branch's state. 



e specified. 



in an improper context. See Chapter 6 for details, 
itive value upon success if the caller set TMASYNC (see 

xa_forget 0 , xajopen () , xa_prepare () . 



s perspective, the pointer xid is valid only for the duration 
That is, once the function completes, either synchronously 
manager is allowed to invalidate where xid points, 
ged to use private copies of *xid after the function 



er courai 
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xa_start ( 



NAME 



xa^ itart — start work on t ehalf of a transaction branch 



SYNOPSIS 

#ir 

int 
xa 



elude "xa.h" 



start (XID *xid, int 



DESCRIPTIPN 

A 
ma 
par 
recrt; 
thn 



tijansaction manager cal 
do work on behalf c 
icipate in a branch am 
gnise whether or not 
ad's resource manage: 
acti /e thread to release 
mu: t call this function 
manager. If the resource 
beh ilf of the application, x i. 



xa_start{) to inform a resource manager that an application 
a transaction branch. Since many threads of control can 
each one may be invoked more than once, xa_start() must 
the XID exists. If another thread is accessing the calling 
br the same branch, xa_start{) may block and wait for the 
control of the branch (via xa_end{)). A transaction mcinager 
the same thread of control that accesses the resource 
manager is doing work outside any global transaction on 
i^startQ returns [XAER_OUTSIDE] . 



fr )m 



A ti ansaction manager ca 
hav ! TMREGISTER set in 
mai agers with TMREGIS' 
ax_i sgQ for details) 

The first argument, xid, is 
witl the calling thread of 
unic ue for different trans 
new 



branch qualifier withi i 
asscJciation (that is, when 
the ransaction manager 
resojrce manager for the 
man ager that it is doing so 



If th 
loos ;ly 

may 



transaction 
coupled to the othe|r 

treat this thread's 
isola tion policies. If the 
thread is tightly-coupled 
guai antee that tightly-cou 
isola :ion policies and that 
coup led threads. 



The hrgument rmid, the 
calliqig xa_openO, identifies 



Folic wing are the valid setti igs of flags 
TMJOIN 



his flag indicates tha: 
ransaction branch 
1 ransaction context so 
leadlock within the branch 
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rmid, long flags) 



s xa_startQ only for those resource managers that do not 
the flags element of their xa_switch_t structure. Resource 
ER set must use ax_regO to join a transaction branch (see 



pointer to the XID that a resource manager must associate 
ontrol. The transaction manager guarantees the XID to be 
ction branches. The transaction manager may generate a 
the XID when it calls xa_startO for a new thread of control 
MRESUME is not set in flags; see TMRESUME below). If 
ects to reuse a branch qualifier previously given to the 
XID, the transaction manager must inform the resource 
by setting TMJOIN in flags; see TMJOIN below). 



manager generates 



a new branch qualifier in the XID, this thread is 
threads in the same branch. That is, the resource manager 
'v\|ork as a separate global transaction with respect to its 
transaction manager reuses a branch qualifier in the XID, this 
the other threads that share the branch. An RM must 
ed threads are treated as a single entity with respect to its 
] lo deadlock occurs within the branch among these tightly- 



13 



sapne integer that the transaction manager generated when 
he resource manager called from the thread of control. 



the thread of control is joining the work of an existing 
he resource manager should make available enough 
1 hat tightly-coupled threads are not susceptible to resource 



52 



X/Open CAE Specification (1991) 



Reference k anual Pages 



TMRESUME 

This flag indicates 
transaction branch 
transaction context 
the suspend, as if th 
other threads in the g 



tm: 



RETURN VA 

The 



f a resource manaj 
XAER_NOTA]. Nojie 
TMRESUME. 



xa_start() 



er does not recognise *xid, the function fails, returning 
that this flag cannot be used in conjunction with 



that 



a thread of control is resuming work on the specified 
le resource manager should make available at least the 
is specific to the resource manager, present at the time of 
thread had effectively never been suspended, except that 
obal transaction may have affected this context. 



tlat 



its 



f a resource manag 
XAER_NOTA]. Ifth 
different thread fron 
manager expressed 
lag on xa_endO), the 
the work. Otherwisi 
manager returns [XA: 
manager uses the 
association. 



er 



does not recognise *xid, the function fails, returning 
resource manager allows an association to be resumed in a 
the one that suspended the work, and the transaction 
intention to migrate the association (via the TMMIGRATE 
urrent thread may be different from the one that suspended 
the current thread must be the same, or the resource 
ER_PROTO]. When TMRESUME is set, the transaction 
s^me XID it used in the XcuendQ call that suspended the 



f *xid contains a 
multiple outstanding 
apply: 



re used 



• The transaction 
withTMMIGRAT 



m inager 



Moreover, the transaction 
that currently has 



t' 



to 



TM^ lSYNC 

This flag indicates 
success, the function 
use as an argument 
calling thread of contJol 
same resource manage : 

TMr fOFLAGS 

This flag must be usee 



UE 

unction xa_startQ has 



[XA. RETRY] 

TMNOWAITwasset 
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branch qualifier, and the transaction manager has 
luspended thread associations for *xid, the following rules 



can have only one of them outstanding at any time 
set in flags. 



manager cannot resume this association in a thread 
non-migratable suspended association. 



These rules prevent ar ibiguity as to which context is restored. 

OWAIT 

When this flag is 
:XA_RETRY] and the 
control with *xid (that 
in conjunction with Tl^pASYNC 



et and a blocking condition exists, xa_startO returns 
resource manager does not associate the calling thread of 
is, the call has no effect). Note that this flag cannot be used 



at xa_startO shall be performed asynchronously. Upon 
turns a positive value (called a handle) that the caller can 
xa_completeO to wait for the operation to complete. If the 
already has an asynchronous operation pending at the 
, this function fails, returning [XAER_ASYNC]. 



when no other flags are set in flags. 



he following return values: 



I Sags and a blocking condition exists. 



pedfication 
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[X4_0K] 

Normal execution. 



[X/ 



RB*] 



The resource manager has not associated the transaction branch with the thread of 
control and has marked *xid rollback-only. The following values may be returned 
regardless of the setting of flags: 

[XA_RBROLLBACK] 

The resource manager marked the treinsaction branch rollback-only for an 

unspecified reasc 

[XA_RBCOMMFAIL]l 

A communication failure occurred within the resource manager. 

[XA_RBDEADLOCK] 

The resource maijager detected a deadlock. 

[XA_RBINTEGRITY] 

The resource maijager detected a violation of the integrity of its resources. 

[XA_RBOTHER] 

The resource mdiager marked the transaction branch rollback-only for a 
reason not on thi^list. 

[XA_RBPROTO] 

A protocol error c[ccurred within the resource manager. 

[XA_RBTIMEOUT] 

The work represented by this transaction branch took too long. 

[XA_RBTRANSIENT] 

The resource manpger detected a transient error. 

[XA£R_ASYNC] 

TMASYNC was set if Bags, and either the maximum number of outstanding 
asynchronous operations has been exceeded, or TMUSEASYNC is not set in the 
flags element of the respurce manager's xa_switch_t structure. 

[XA]fR_RMERR] 

\n error occurred in a^ociating the transaction branch with the thread of control. 

[xa]:r_rmfail] 

\n error occurred thatjrnakes the resource manager unavailable. 
[XAiR_DUPID] 

neither TMRESUMEl nor TMJOIN was set in flags (indicating the initial use of 
■■xid) and the XID already exists within the resource manager, the resource 
inanager must return |jXAER_DUPID]. The resource manager failed to associate 
le transaction branch fvith the thread of control. 

[XAriR_OUTSIDEl 

'he resource manager jis doing work outside any global transaction on behalf of 
t he application. 



54 



X/Open CAE Specification (1991) 



Reference M mual Pages 



SEE ALSO 

ax 



WARNINGS 



[x4er_nota] 

Either TMRESUME (Ir 
known by the resourc 

[X^ERJNVAL] 

Invalid arguments wefre 

[Xy^ER_PROTO] 

The routine was invo 



The function returns a 
above) in ^ags 



ed in an improper context. See Chapter 6 for details, 
pdsitive value upon success if the caller set TMASYNC (see 



/ egO, xa_completeO , xa 



Froi ri the resource manage 
of tl le call to xa_starti) 
asyr ichronously, the 
Resource managers are 
com pletes. 



s perspective, the pointer xid is valid only for the duration 
T lat is, once the function completes, either synchronously or 
transaction manager is allowed to invalidate where xid points, 
encouraged to use private copies of *xid after the function 



xa_start() 



TMJOIN was set in Hags, and the specified XID is not 
manager. 

specified. 



d{),xa_openO. 



Distributed Trans iction Processing: The XA S jeciflcation 
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■ Chapter 6 

I State Tables 



This 



chapter contains statejtables that show legal calling sequences for the XA routines. 
TMt must sequence their juse of the XA routines so that the calling thread of control 
mal ;es legal transitions thJough each applicable table in this chapter. That is, any TM 
mu; t, on behalf of each AFithread of control: 



• open and close each Rr 

• associate itself with, ai 
' 'able 6-2 on page 59 or] 

• i dvance any transactii 
{ hown in Table 6-4 on 

• I lake legal transitions 
r outines in the asynchn 

Table 6-5 on page 63 is tl 
rout nes. The other tables 
this :ase, the tables view tj 
call 1 hat shows that the opt 



All 
That 



same 
valic 
state 



as shown in Table 6-1 on page 58 

id dissociate itself from, transaction branches as shown in 
'able 6-3 on page 60, whichever applies 

jn breinch toward completion through legal transitions as 

ige62 

through Table 6-5 on page 63, whenever the TM calls XA 
Inous mode. 

only table that addresses the asynchronous mode of XA 
Iso describe routines that can be called asynchronously. In 
e XA Ccill that initiates an operation, and the xa_completeO 
ation is complete, as a single event. 



Inte; pretation of the Tablec 

A sii igle call may make trsjnsitions in more than one of the state tables. Services that 
are r 



ot pertinent to a given fetate table are omitted from that table. 



t le 



tables describe the atate of a thread of control with respect to a particular RM. 
is, the tables indicatelthe validity of a sequence of XA calls only if the calls all 
pertain to the same RM. Tile thread of control could be dealing with other RMs at the 
time, which might be in entirely different states. Each state table indicates the 
initial state or states nor such a sequence; it is not alwa}^ the leftmost state (the 
with the zero subscript) . 



Tabl( 6-2 on page 59, Tab! 
sequi ;nce of calls with respj 
the s ime RM thread of coi 
creat on through completioj 
at a 1 ime. Thus, while one 
sam^ thread of control may 



6-3 on page 60 and Table 6-4 on page 62 describe the 
ct to the progress of a particular XID. Other XIDs within 
rol may be in different states as they progress from initial 
, except that a thread can have only one active association 
D may be actively associated in a thread of control, the 
ke branch completion calls for other XIDs. 



entry 



An 
that £ 

the n utine 
unless 



under a particular Jstate in the table asserts that an XA routine can be called in 
tate, and shows the resulting state. A blank entry asserts that it is an error to call 
in that state. The routine should return the protocol error [XAER^PROTO], 
another error code that gives more specific information also applies. 
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Noi ation 

Son letimes a routine makep 

or c nly when the routine 
table entries describe th;se 
par jntheses, even thoug i 
xa_( ndCTMFAIL) describe? 
the flags argument. The ta jles 
using an arrow (->) followed 



For Example, the legend 

:a_end^ [XA_RB] 
describes the case where a 
Ag 



H ineral state table entry 
remaining cases of calls 
returns success. (The xa_ 
_OK].) Calls that retlirn 



[TMj 

des( ribed by specific state 



The 



notation xa_* refers to 



6.1 Res ource Manager Ii itialisation 



For 
(Ro) 



A tr; 
inclu 

precl 



a state transition only when the caller gives it certain input, 
etums certain output (such as a return code). Specific state 
cases. The tables describe input to the routine in 
that may not be the exact syntax used; for example, 
a call to xa_endO in which the caller sets the TMFAIL bit in 
denote output from the routine, including return status, 
by the specific output. 



< iach thread of control 
The xa_openO and 



all to xa_end{) returns one of the [XA_RB*] codes. 



one that does not show flags or output values) describes all 
that routine. These general entries assume the routine 
routines return the [XA_OK] code; the ax_ routines return 
failure do not make state transitions, except where 
able entries. 



ill applicable xa_ routines. 



, 3ach RM is either open or closed. The initial state is closed 
xa_closeO routines move an RM between these states. 
Redthndant uses of these ro itines are valid, as Table 6-1 shows: 



XAI 


outines 


Resource Manager States 


Un-initialised 
Ro 


Initialised 

Ri 


xa_p 
xa_a 


en{) 
ise 


Ri 
Ro 


Ri 
Ro 



Table 6-1 St^ ite Table for Resource Manager Initialisation 



nsition to Ri enables 



jdes its use in glob 



sequ( inces. 

In Taale 6-2 on page 59 to 



:he use of Table 6-2 on page 59 to Table 6-4 on page 62 



Jive. The state Rq a )pears in these tables to illustrate that closing an RM 



il transactions. At this point, Table 6-1 governs legal 



able 6-4 on page 62 a return of [XAER^RMFAIL] on any 



routii le causes a state transii ion in that thread to state Ro 
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Association of Threads of Control with Transactions 



6.2 As sociation of Threads of Control with Transactions 

Tatle 6-2 shows the stale of an association between a thread of control and a 

trai isaction branch. (See ikble 6-3 on page 60 for RMs that dynamically register with a 
TM,) Valid initial states ef association for a thread of control are Tq and T2. (The 
Association Suspended state, T2, includes the case where a thread has suspended an 
assdciation migratably. After returning to Tq, any thread can re-enter this table in 
coh imn T2 to resume or erjd that other association.) 

Tab e 6-2 makes the foUomng assumptions: 

'he calling thread remains in state Ri . 

The RM does not have tTMREGISTER set in its switch. 

he caller passes the spme rmid and XID as arguments to each applicable routine 

listed below. 

Tab e 6-2 shows the efFefct of xa_start{) and xa_endO on the thread of control's 
assc elation with a single tJansaction branch. These routines may also change the state 
of tl e branch itself. Therefore, Table 6-4 on page 62 further constrains their use. 

If a bread suspends its association, it can perform work on behalf of other transaction 
brarlches before resuming me suspended association. 







Transaction Branch Association States 


XARoutiii 




Not 


Associated 


Association 






Associated 




Suspended 






To 


Tl 


T2 


xa_starti) 




Tl 






xa_start (TMRESUME 








Ti 


xa_start (TMRESUME 


-> [XA_RB] 






To 


xa_eJ7d(TMSUSPEND 






T2 




xa_end(TMSUSPEND 


^ [XA_RB] 




To 




xa_enc/ (TMSUCCESS) 






To 


To 


xa_end{TMFAIL) 






To 


To 


xa__open{) 




To 


Tl 


T2 


xa^recoverO 




To 


T, 


T2 


xa^closeO 




Ro 




Ro 


xa_*()^[XAER_RM 


FAIL] 


Ro 


Ro 


Ro 



Table 6-2 State Table for Transaction Branch Association 
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Association if Threads of Control v ith Transactions 



State Tables 



6.2.1 Dy 



60 



the 
Do. 



lamic Registration ( 



Tab e 6-3 shows the sta 

trar 



of an association between a thread of control and a 

saction branch. This ffable is for RMs that dynamically register with a TM. Valid 
initial states in Table 6-3 ar ; Dq and D2. (The Association Suspended state, D2, includes 

h IS suspended an association migratably. After returning to 
enter this table in column D2 to resume or end that other 



case where a thread 
any thread can re-i 



assc ciation.) 

The top half of the table sHows 
The bottom half of the t; 
com rol. The thread of coritrol 
half of the table, 



Tab: 



Tab 



e 6-3 makes the follow 
he TM calling thread 
heRMhasTMREGIS' 



he same RM and XID 



Threads 



the legal sequence of calls for an RM thread of control, 
ble shows the legal sequence of calls for a TM thread of 
calling these routines must comply with the applicable 



ng assumptions: 
i^mains in state Ri . 
ER set in its switch. 



he caller passes the s^me rmid and XID as arguments to each applicable routine 
listed below. 



re used for the dynamic registration functions. 



6-3 defines the beha^ 
susplends its association 
resu Tiing the suspended association. 



iour of a single transaction branch in a thread. If a thread 
can perform work on behalf of other branches before 



XA Routines 



Re? ource Manager Calls 



ax_ reg valid XID 
a/J-eg-^NULLXID 

ax_ 
ax_ 



feg^[TM_RESUME] 
mreg 



Tra isaction Manager Calls 



xa_ 
xa_ 
xa_ 
xa_ 
xa 



;nc/(TMSUSPEND) 
;nd (TMSUSPEND) 
mdCTMSUCCESS) 
:n(/(TMFAIL) 
ipen() 



xa_recover{) 



xa_ 
xa_ 



[Xj i_m 



0 ^ [XAER.RMFAIL] 



Transaction Branch Association States 



Not 
Registered 

Dn 



D3 



Do 
Do 

Ro 
Ro 



Registered 

with 
Valid XID 
Di 



D2 
Do 
Do 
Do 
Di 
Di 

Ro 



Registration 
Suspended 

D, 



Di 



Do 
Do 
D2 
D2 

Ro 
Ro 



Registered with 
NULLXID 

D, 



Dn 



D3 
D3 

Ro 



T< ible 6-3 State Table for Transaction Branch Association (Dynamic Registration) 
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6.3 



Transaction States 

Table 6-4 on page 62 sho^ /s 
Stat ; listed in Table 6-4 on 
conrol. The table applies 



the commitment protocol for a transaction branch. Any 
3age 62 except state Si is a valid initial state for a thread of 
sequential calls by a thread of control that: 



• remains in state R 



)asses the same XID in 



Tab e 6-4 on page 62 
trar saction branch. These 
braijich. Therefore, Table 6 
use 



Tab 



xa_s tart (TMRESUME) or a f 
;onstrained by Table t 



are 
rulet 



;« a_eiicl (TMSUSPEND 
c ssociation for this brajich 
easures that there exi 
1: ranch.) 



A a_starf (TMRESUME) 

branch that has at 
must either have 
sjspended migratably 
V hich was suspended 



. xB_en(/(TMSUCCESS) 
irrent thread or that 
sociated with the currfent 
suspended associatio i 
derformed (see above) 



each xa_ call that requires an XID. 

shqws the effect of xa_start{) and xa_endQ on the state of a 
routines may also change the thread's association with the 
on page 59 and Table 6-3 on page 60 further constrain their 



6-4 on page 62 



n lay I 
let St 
bee n 
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does not apply to uses of xa_enc/ (TMSUSPEND), 
reg in which [TM_RESUME] is returned; the uses of these 
2 on page 59 and Table 6-3 on page 60 and the following 



VIMIGRATE) may be used only if no other thread 
was suspended with the TMMIGRATE flag. (This rule 
ts at most one migratable suspended association for a 



be used, and ax_reg may return [TM_RESUME], only on 
one suspended association. That suspended association 
suspended non-migratably by the acting thread or 
)y any thread. If both conditions are true, the association 
rion-migratably by the acting thread is the one resumed. 



nfay be used only on a branch that is associated with the 
las at least one suspended association. If the branch is 
thread, it is that association which is ended. Otherwise, 
ends, as though an implicit xa_start(TMRESUME) were 
2fore the xa_enc/(TMSUCCESS). 
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Transaction 



States 



State Tables 



Note s: 
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Table 



t This row alsc 
informs the R] 





XA Koutines 




Transaction Branch States 


Non-existent 
Transaction 
So 


Active 

Si 


Idle 

S2 


Prepared 

S3 


Rollback 

Only 
S4 


Heuristically 
Completed 

S5 


t 


xajstarti) 




Si 




Si 








t 


xa_start{) h> [XA_RB] 








S4 










xa_end{) 






S2 










t 


xa_end{) [XA_RB] 






S4 












xa_prepare{) 








S3 










xa_prepare{) 








So 








i 


[XA_RDONLY] or 


















[XA_RB] 


















xa_preparei) —> 








S2 










[XAER_RMERR] 


















xa_coinmit{) -» 








So 


So 








[XA_OK] or 


















[XAER_RMERR] 
















t 


xa_coiimit() [XA_RB 








So 










xa_conanit(,) -» 










S3 








[XA_RETRY] 


















xa_commit{) -> 








S5 


S5 




S5 


t 


[XA_HEUR] 


















xa_rollbackO -> 








So 


So 


So 




t 


[XA_OK] or [XA_RB] ( 


r 
















[XAER_RMERR] 


















xa_roIlback(,] -» 










S5 


S5 


S5 


t 


[XA_HEUR] 


















xa__forget{) 














So 




xa_forget{) 














S5 




[XAER_RMERR] 


















xa_open{) 




So 


Si 


S2 


S3 


S4 


S5 




xa_recover{) 




So 


Si 


S2 


S3 


S4 


S5 




xa_close{) 




Ro 




Ro 


Ro 


Ro 


Ro 




xa_*{) —> 




Ro 


Ro 


Ro 


Ro 


Ro 


Ro 




[XAER_RMFAIL] 
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applies when an applicable RM calls ax_reg and the TM 
A that its work is on behalf of a transaction branch. 



[XA_HEUR] denotes any of [XA_HEURCOM], [XA_HEURRB], 
[XA_HEURMX], or [XA_HEURHAZ]. [XA_RB] denotes any return 
value with a p refix [XA_RB. 
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State Tables 



Tab 



6 .4 As ^nchronous Oper ations 



acc( (unt asynchronous ope rations 



Tab 



e 6-5 illustrates that or 



beh ilf of an XID, the only 



XIE 



is the corresponding > a_completeO. For those routines that do not take an XID, the 



thr^d must wait for the c aeration's completion before issuing another request to that 
RM. The only routi: les by which the TM can give additional work to the same 
are xajcommiti) , xa_foi jef () , xa_prepare () , and xa_roUback Q . 



sam 
RM 

The 



valid initial state for a 



(w ith TMASYNC) achieve a state transition in Table 6-5 when 
va id handle (a positive value). The table entries describing 
xa_dpmplete{) assume that 1 le caller passes this same, valid handle to xa_complete{). 



The 
the 



asynchronous calls 
xinction returns a 



Asynchronous Operations 



le 6-5 describes async ironous operations. The preceding tables do not take into 



ce a TM thread makes an asynchronous request to an RM on 
valid request the TM thread can give the same RM for that 



iread of control is Aq. 



XARo 


tines 


Asynchronous Operation States 


Initial Call 

Ao 


Operation Pending 

Aa 


Any s3mchronous xa_= 
xa_rollback (TMASYNC 

xa_dose (TMASYNC) 
xa_comniit(TMASYNC 
xa_end (TMASYNC) 
xa_/orget (TMASYNC) 
xa_open (TMASYNC) 
xa jjrepare (TMASYNC 
x-a_start (TMASYNC) 
xa_coinplete{) 
xa_complete (TMNOW; 
xa_compiete(TMNOW; 


call 
) 

IT) 

IT) ^ [XA_RETRY] 


Ao 
Ai 
Ai 
Aa 
Ai 
Aa 
Ai 
Aa 
Aa 


Ao 
Ao 
Aa 



Table 6-5 



State Table for Asynchronous Operations 
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State Tables 
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/ 



Thi > chapter summarises t le implications on implementors of this specification. It also 
idei itlfies features of this s Decification that implementors of RMs or TMs can regard as 
opt onal. 



cod 
the 
by: 



Chapter 7 

Implementation Requirements 



These requirements are d 
move a software component 
It is anticipated thai 
administrator will con 



signed to facilitate portability — specifically, the ability to 
to a different DTP system without modifying the source 
DTP products will be delivered as object modules and that 
rol the mix and operation of components at a particular site 



re-linking object moc ules 



supplying text strirg: 
supplied procedure 



t lat 



7. 1 Ap plication Progran i Requirements 



Any 



AP in a DTP system n 



ust use a TM and delegate to it responsibility to control and 
cooijdinate each global tran saction. X/ Open will specify a TX interface separately. 



The 
AP 

The 



AP is not involved in 
i hread can have only 



AP may ask for work 
native interface exactly as 
defii le global transactions 



f ither the commitment protocol or the recovery process. An 
oi|e global transaction active at a time. 

to be done by calling one or more RMs. It uses the RM's 
it would if no TM existed, except that it calls the TM to 
lee Section 7.2.1 on page 68). 



;s to the software components (or executing a vendor- 
generates suitable text strings). 
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Resource Mi nager Requirements 



7.2 Re source Manager I equirements 



The 



affects only RMs operating in the DTP environment, 
mo^el puts these constrair ts on the architecture or implementation of the RM: 



X/Open DTP model 



nterfaces 

^Ms must provide all t 
particular routine 
1 lative application pro 
initial version of the 
their switches. 



le xa_ routines specified in Chapter 3 for use by TMs, even if 
requires no real action by that RM. RMs must also provide a 
ram interface (see Section 7.2.1 on page 68). As this is the 
interface, RMs must also set to 0 the version element of 



1 ^n RM in an executable 



i ability to recognise XI )s 
1 IMs must accept XIDs 
t ley do for an AP. Fo : 
f rocess identifier, the RM 



I m important attribute 
t le bits in the data po 
T lust not alter in any 
I M remotely communii 
r ot altered by the 
treated as an OCTE 
'erenced ASN.l 



he 



r 3 



• C ailing protocol 

. single instance of an 
behalf of the same 



on 



M must allow multiple threads logically to gain access to it 
xansaction branch, although it has the option of actually 
iijnplementing single-th: eaded access (for example, blocking a thread at the call to 
xi_starti) or channellin all accesses through a single back-end process). An RM 
can use whatever it wi;hes from the AP's environment (for example, process ID, 

ntify the calling thread. 



tf sk ID, or user ID) to id 



A n RM must ensure 
aid must return [XAEl 
s1 ate tables (see Chapter 



Implementation Requirements 



The 



module is linked to at most one TM. 



from TMs. They must associate with the XID all the work 
example, if an RM identifies a thread of control using a 
must map the process identifier to the XID. 



stand ird 



Df the XID is global uniqueness, based on the exact order of 
tion of the XID for the lengths specified. Therefore, RMs 
the bits in the data portion of the XID. For example, if an 
:ates an XID, it must ensure that the data bits of the XID are 
process. That is, the data part of the XID should 
' STRING (opaque data) using terminology defined in the 
and the referenced BER standard. 



w^ ly 



comr lunication 



thit 



each calling thread makes xa_ calls in a legal sequence, 
:_PROTO] or other suitable error if the caller violates the 
6). 



• CDmmitment protocol 
T le RM must support tte commitment protocol specified in Section 2.3 on page 8. 
T lis has the following in iplications: 



An RM must provl 
whether it can 
reports that it can, 
branch. It must 
roll back the branch 



e an xa_prepareO routine, and must be able to report 
guaijantee its ability to commit the transaction branch. If it 
t must reserve all the resources needed to commit the 
holdlthose resources until the TM directs it either to commit or 



An RM must suppor : 
page 8). That is, it 
it has not yet receivec 



the one-phase commit optimisation (see Section 2.3.2 on 
mtist allow xa_commit{) (specifying TMONEPHASE) even if 
xa_prepareO for the transaction branch in question. 
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Implementai ion Requirements 



support for Recovery 

\n RM must track th< 
\fter responding affirn latively 
cnowledge of the brani h 
t receives and succes; fully 
branch. If an RM heur: 
ixplicitly permitted to 
)ranches that it has 



Vhen an RM recovers 
( :ompleted transaction 



ublic information 

. ^n RM product must pjublish the following information: 



The name of its xa. 
other information; 
may share the same 
routine, even pointers 
must return in an or ierly 
not need to publish 



Resource Manager Requirements 



status of all transaction branches in which it is involved, 
to the TM's xa_preparei) call, the RM cannot erase its 
or of the work it has done in support of that branch, until 
performs the TM's order to commit or roll back the 
stically completes a branch, it cannot forget the branch until 
)y the TM. On command, an RM must return a list of all its 
to commit or has heuristically completed. 



pre aared 



from its own failure, it recovers prepared and heuristically 
)ranches. It forgets all other branches. 



>witch_t structure. This switch gives RM entry points and 
ection 4.3 on page 21 specifies its structure. Multiple RMs 
xa_switch_t structure. Each pointer must point to an actual 
that are theoretically unused on that RM. These routines 
way, in case they are mistakenly called. (The RM does 
he names of the individual routines.) 



The text of the string 



The forms of the 

accept, and the wa 
domains for differen 



irJFormation strings that its xa_openO and xa_closeQ routines 
that different xa_openO strings specify different resource 
RM instances. 



The names of librbries 
administrator must i ise 



X/Open will specify 
onflict with the name 
a lother organisation. 

Ii nplementor options 

E ich RM has the option 



Any semantics in th< 
for example, specif] 
differ from non-DTP 



native interface that alfect global transaction processing — 
ing isolation level, transaction completion, or effects that 

operation. 



h )w 



an RM provider can guarantee that its names do not 
of any other RM product or version produced by that or 



jf implementing these features: 



Open/close informaiional 
Any RM may accept 
on calls to its xa_opei 
fact.) 



Protocol optimisatio is 

The read-only optim 



Association migratiqn 
An RM can allow a 
other than the one w 



within the RM switch, that specifies the name of the RM. 



or object files, in the correct sequence, that the 
when linking APs with the RM. 



strings 

a null string in place of the informational string argument 
) and xa_closeO routines. (If it does so, it must publish this 



i sation discussed in Section 2.3.2 on page 8 is optional. 



\A to resume a suspended association in a thread of control 
ere the suspension occurred. 
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Resource M \nager Reqvdrements 



Implementation Requirements 



7.2.1 The 



Branch identificati( in 

An RM can use t le bqual component of the XID structure to let different 
branches of the sai ne global transaction prepare to commit at different times, 
and to avoid deadlc ck (see Section 4.2 on page 19). 

Dynamic registratii )n 

This feature, as des( ribed in Section 3.3.1 on page 15, is optional. 
Asynchrony 

Support for the as ynchronous mode discussed in Section 3.5 on page 18 is 
optional. If the T^ [USEASYNC flag is set in the RM's switch, the RM must 
support the asynchronous mode. It may still complete some requests 
synchronously, eith gr when the TM makes the original asynchronous call or 
when the TM calls xa_completeO. If the TMUSEASYNC flag is not set in the 
RM's switch and t le TM makes an asynchronous call, the RM must return 
[XAER_ASYNC]. 



Heuristics 

As described in the 
RM can report that 
feature is optional. 



xa_commitO and xa_roHbackO reference manual pages, an 
it has heuristically completed the transaction branch. This 



Application Prograi i (Native) Interface 



In tl 



RMs must provide a well 
max mise portability, all 
pub! ication. For example, 
refer enced SQL specificatic 



fi DTP environment, 



Som; RMs, such as some 
have 



trans 



s actions. An AP must 
knov dedge of an RM's 
an SQL RM in the DTP 
glob, il transaction: 

EKEC SQL COMMIT W< 
E ^CEC SQL ROLLBACK 



■ary 



[ glo )al 



c efined native interface that APs can use to request work. To 
RM interfaces should adhere to any applicable X/Open 
1 relational DBMS RM should use the SQL defined in the 



n. 



uMs must rely on the TM to manage global transactions. 
Indexed Sequential Access Method (ISAM) file managers, 
no concept of transac ions. So this is a new requirement, but it does not change 
the native interface. In oth sr RMs, such as SQL RDBMSs, the native interface defines 

lot use these services in a DTP context, since TMs have no 
tran iaction. For example, the application program interface for 
er v^ironment must not let use of these statements affect the 



3RK 
WORK 



In adjdition, any service in t^ie native AP-RM interface that affects its own commitment, 
or i 

ai 



non-standard service 
transaction. 



that has an effect on transactions, must not be used within 
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7.3 Tn insaction Manage r Requirements 



Service interfaces 

TMs must use the xa. 
vork of ail the local Rl /[s 
I m any local RM associ ited 
( :alls addresses the con jct 



routines the RM provides (see Chapter 3) to coordinate the 
that the AP uses. TMs must call xa_openQ and xa_closeQ 
with the TM. Each TM must ensure that each of its xa_ 
RM. 



t) 



Ms must be written 

ian legally return. A 
]iM options that this 
object program, dynantii 
£ nd RMs that use the re ad- 



handle consistently any information or status that an RM 
must assume that it may be linked with RMs that use any 
sjaecifiication allows, including multiple RMs in a single AP 
c registration of RMs, RMs that make heuristic decisions, 
only protocol optimisation. 



ransaction identifiers 

A TM must generate X 
page 19. They must 
t 'ansaction branch. To 
OBJECT IDENTIFIER 
s tandard) that the TM 
TM should also use 
same OBJECT IDENTIFHER 
b qual fields identify the 
V dth which they are 



Failure to use the 
ii iteroperability proble 
ti ansaction or affect shaled 



Pjublic information 

TM product must pu 



linking directions 
directions must de: 
incorporate the swit(lh 
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Ds conforming to the structure described in Section 4.2 on 
36 globally unique and must adequately describe the 
guarantee global uniqueness, the TM should use an ISO 
ee the referenced ASN.l standard and the referenced BER 
nows is unique within the gtrid component of the XID. The 
ISO OBJECT IDENTIFIER within the bqual field, but the 
can be used for all XIDs that a given TM generates. The 
M that generated them, and identify the transaction branch 
assJ)ciated. 



ai! 



ISD 



n s 



OBJECT IDENTIFIER format for XIDs could cause 
when multiple TMs are either involved in the same global 
resources. 



lish the following information: 



3r producing an application object program — these 
cribe how to link RM and TM libraries, and how to 
from each RM 



instructions for gene 
TM uses when it call 



ating or locating appropriate informational strings that the 
xa_open () or xa_doseQ for each RM 



Ii iplementor options 
T le one-phase commit )rotocol optimisation (see Section 2.3.2 on page 8) and the 
a; ynchronous and non-1 locking modes for calling RMs (see Section 3.5 on page 18) 
ai e optional. 
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■ Appendix A 

/ Comple 



omplete Text i )/ "xa.h" 



This appendix specifies tl le complete text of an "xa.h" file in both ANSI C (see the 
refe 'enced C standard) an< Common Usage C. 

/* 



tart of xa.h header 



* I 



def XA_H 
ine XA H 



=fine a symbol to pi 

*/ 
#ifi 
#dei 
/* 

* llransaction branch ic^ntif ication 
*/ 
#def 
#def 



28 
4 
«4 



ine XIDDATASIZE 
ine MAXGTRIDSIZE 
#define MAXBQUALSIZE 
stri; ct xid_t { 
Icng formatID; 
long gtrid_length; 
Ic ag bgual_length 
chjar data [XIDDATASIZE] 

}; 

typejaef struct xid_t XXD 
/* 

value of -1 in formlitlD means that the XID is null. 



A 



* Declarations of routii^es by which RMs call TMs: 
*/ 



#ifd^f 
exte: 
exte: 
#els^ 

exte 
exte 
#end 
/* 

* XA 

*/ 

#def 



chi 



event multiple inclusions of this header file 



XID and NULLXID: 



/* 
/* 



size in bytes */ 

maximum size in bytes of gtrid */ 



/* maximum size in bytes of bqual */ 

/* format identifier */ 
/* value from 1 through 64 */ 
/* value from 1 through 64 */ 



STDC 

n int ax_reg(int, X 

n int ax_unreg ( int , 

/* ifndef STDC 

n int ax_reg ( ) ; 
n int ax_unreg ( ) ; 



f /* ifndef 



STDC 



Switch Data Structi re 



ne RMNAMESZ 



defile MAXINFOSIZE 



struc t xa__switch_t { 



r name [RMNAMESZ] 



loig flags; 
lorg version; 

#ifd€f STDC 

int (*xa_open_entry) (ch^r 
int (*xa_close_entry) (c 
int {*xa_start_entry) (X 
inq (*xa_end_entry) (XID 



D *, long) ; 
long) ; 

/ 



*/ 



/* 
/* 
/* 
/* 



length of resource manager name, */ 
including the null terminator */ 
maximum size in bytes of xa_info 
strings, including the null terminator*/ 



/* name of resource manager */ 

/* options specific to the resource manager */ 

/* must be 0 */ 



lar * 

;d *, 



int, long) ; 

int, long) ; 
int , long) ; 



*, int, long) ; 



/* xa_open function pointer*/ 
/* xa_close function pointer*/ 
/* xa_start function pointer*/ 
/* xa_end function pointer*/ 
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Complete Text of "xa.h" 



i: It 



i; It 
1: It 
i: It 



lUt 

iiit 



#eldie 

±3 it 

iiit 
ii.t 
iit 
ii 
ii 
ii 
ii 
iit 
ir t 
#enqi 
} 

/* 

* Ejlag definitions for 

*/ 

#defline TMNOFLAGS 0x0 

#define TMREGISTER 0x0 



#def 



ine TMNOMIGRATE 0x0 
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(*xa_rollback_enti /) 



{*xa_prepare_entr-5( ) (XID 
(*xa_conimit_entry) (XID *, 
(*xa_recover_entry ) (XID 

(*xa_forget_entry) (XID *, 
(*xa_complete_ent3: i^) (int 



/* ifndef STDC 

(*xa_open_entry) () 
(*xa_Glose_entry) ( 
(*xa_start_entry) ( 
(*xa_end_entry) () ; 
(*xa_rollback_entr 
( *xa_prepare_entry 
( *xa_Gommit_entry) 
(*xa_recover_entry 
(*xa_forget_entry) 
( *xa_conpl et e_ent r 
f /* ifndef STDC 



ttdeftine TMUSEASYNC 0x0 

/* 

* FjLag definitions for 
*/ 

/* ufee TMNOFLAGS, define 
#def Lne TMASYNC 0x8 C 

#def Lne TMONEPHASE 



0x2 

0x1 
0x0 



#def 

#def 
#def 

#def 

#def 

#deflne TMSTARTRSCAN 0x0 
#def ; ne TMENDRSCAN 
#def ; ne TMMULTIPLE 
#def : ne TMJOIN 0x00 

#def]ne IMMIGRATE 



.ne TMFAIL 

ne TMNOWAIT 
ne TMRESUME 

ne TMSUCCESS 

ne TMSUSPEND 



(XID 



*/ 



0 ; 
0 ; 
) ; 

0 ; 



0 ; 

*/ 



*, int, long) ; 

/* xa_rollback function pointer*/ 
, int, long) ;/* xajrepare function pointer*/ 

int, long) ; /* xa_commit function pointer*/ 
, long, int, long) ; 

/* xa_recover fiinction pointer*/ 
int, long) ; /* xa_forget function pointer*/ 
*, int *, int, long) ; 

/* xa_complete function pointer*/ 

/* xa_open function pointer */ 
/* xa_close function pointer */ 
/* xa_start function pointer */ 
/* xa_end function pointer */ 
/* xa_rollback function pointer*/ 
/* xa_prepare function pointer «/ 
/* xa_coimnit function pointer */ 
/* xa_recover function pointer */ 
/* xa_forget function pointer */ 
/* xa_coinplete function pointer*/ 



;he RM switch 

OOOOOL 
OOOOOIL 
000002L 
000004L 



/* no resource manager features 

selected */ 

/* resource manager dynamically 
registers */ 

/* resource manager does not support 
association migration */ 
/* resource manager supports 
asynchronous operations */ 



:a_ and ax_ routines 



above, when not specifying other flags */ 
OOOOOOL /* perform routine asynchronously */ 
Ox4Cl000OO0L /* caller is using one-phase commit 
optimisation */ 
C|000000L /* dissociates caller and marks 

transaction branch rollback-only */ 
OOOOOL /* return if blocking condition exists */ 
OOOOOL /* caller is resuming association 

with suspended transaction branch */ 
OxO4|0OOOOOL /* dissociate caller from transaction 
branch*/ 

Ox02tOOOOOL /* caller is suspending, not ending, 
association */ 
ICOOOOOL /* start a recovery scan */ 
OxOOSOOOOOL /* end a recovery scan */ 
0x00 lOOOOOL /* wait for any asynchronous operation */ 
iOOOOOL /* caller is joining existing transaction 
branch * / 

OxOoB-OOGOOL /* caller intends to perform migration */ 
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Complete Te: :t 



/* 

*/ 

#de:: 



#del 



me 
ine 



#dei 
#del 
/ 

* jfe 

*/ 



me 
ine 



#def ine 

#def ine 

#def 
#def ine 



#def Ine XA RBOTHER 



#def 
#def 
#def 

#def 
#def 



o["xa.h" 



;_() return codes (transaction manager reports to resource manager) 



TM_JOIN 

TM_RESUME 

TM_OK 
TMER_TMERR 

TMER_INVAL 
TMER PROTO 



0 return codes (is 



XA_RBBASE 

XA_RBROLLBACK 

XA_RBCOMMFAIL 

XA_RBDEADLOCK 
XA RB INTEGRITY 



} A 



} A 



RBBASE 

RBBASE+1 

_RBBASE+2 
RBBASE+3 



y. K RBBASE 4-4 



Lne 
Lne 



#def 

#def 

#def 
#def 

ttdefJLne XA 
ttdeflne XA_ 
#def .ne XA 



XA_RBPROTO 

XA_RBTIMEOUT 

XA_RBTRANSIENT 
XA RBEND 



Xi 



X \ 



ne XA_ 

ne XA_ 

ne XA_ 

ne XA_ 

; ne XA 



NOMIGRATE 

HEDRHAZ 

HEURCOM 

HEDRRB 

HEURMIX 

RETRY 

RDONLY 

OK 
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/* caller is joining existing transaction 
branch */ 

/* caller is resuming association with 
suspended transaction branch */ 

/* normal execution */ 

/* an error occurred in the transaction 
manager */ 

/* invalid arguments were given */ 
/* routine invoked in an improper context */ 

source manager reports to transaction manager) 



0 



RBBASE+5 

RBBASE+6 

RBBASE+7 
RBTRANSIENT 



/* the inclusive lower bound of the 

rollback codes */ 

/* the rollback was caused by an 

unspecified reason */ 

/* the rollback was caused by a 

communication failure */ 

/* a deadlock was detected */ 

/* a condition that violates the 

integrity of the resources 

was detected */ 

/* the resource manager rolled back 

the transaction branch for 

a reason not on this list */ 

/* a protocol error occurred in the 

resource manager */ 

/* a transaction branch took too 

long */ 

/* may retry the transaction branch */ 
/* the inclusive upper bound of the 
rollback codes */ 



/* resumption must occur where 

suspension occurred */ 

/* the transaction branch may have 

been heuristically completed */ 

/* the transaction branch has been 

heuristically committed */ 

/* the transaction branch has been 

heuristically rolled back */ 

/* the transaction branch has been 

heuristically committed and rolled back */ 

/* routine returned with no effect and 

may be reissued */ 

/* the transaction branch was read-only and 
has been committed */ 
/* normal execution */ 
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Complete Text of "xa.h" 



#de 
#de 

#de 
#de 
#de 
#de 

#de 
#de 



ine XAER_ASYNC 
ine XAER RMERR 



me 
ine 
ine 
ine 
ine 
ine 



#en(|lif /* ifndef XA_H */ 
/* 

* ^nd of xa.h header 

*/ 
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XAER_NOTA 

XAER_INVAL 

XAER_PROTO 

XAER_RMFAIL 

XAER__DUPID 

XAER OUTSIDE 



/* asynchronous operation already outstanding */ 

/* a resource manager error occurred in the 

transaction branch */ 

/* the XID is not valid */ 

/* invalid arguments were given */ 

/* routine invoked in an improper context */ 

/* resource manager unavailable */ 

/* the XID already exists */ 

/* resource manager doing work outside */ 

/* global transaction */ 
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database management system 5 

DBMS 5 
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decision 

to commit 6 
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uniform ei feet 



DTP system, 
dynamic registration.. 

ofRM 

RM option 

state table . 

use ofRM] 
ending invoHi 



changing., 



declarations, 
definitions 
delivered prAducts 
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